Recurring Processing Failure

Recurring processing can fail when a subscriber or group has insufficient funds or credit to pay recurring charges.

If charges and their applicable discounts cannot be fully applied during cycle processing, the cycle is not processed. No price components are applied, and the state of the balance (for balance cycles) or subscriber or group (for billing cycles and purchased item cycles) remains unchanged.
Note: You can specify in the offer or bundle cycle data properties, or during purchase using the SubMan APIs, that processing can continue if purchase components are applied successfully, but there is insufficient credit to pay the recurring charge at purchase time. For more information, see the discussion about allowing recurring processing failure at the time of purchase.
In cases where recurring processing fails, recurring processing is retried periodically in the current cycle and again in the next cycle. Recurring processing is also retried in the following situations in the current cycle:
  • Every time there is usage or there are queries on the subscriber.
  • A SubMan operation is run that could cause recurring processing to succeed.
    For example:
    • A top-up is made.
    • A product offer or bundle is purchased.
    • A balance is adjusted.
    • A change is made to the attributes of a subscriber or group.
  • Until the period ends.
Recurring processing, retries for each cycle are performed in the order of when the recurring processing was due. If two or more recurring cycles have the same recurring due date, they are processed in priority order. The priority is not evaluated across all recurring cycles. A numerically lower priority value has a higher priority. Consider the following:
  • Recurring processing fails today with two independent offers of priority 10 and 9 with the same recurring cycle time.
  • Tomorrow another offer is set for recurring processing. It has priority 20.
In this scenario, the order of processing is:
  • Due Yesterday: offer priority 9 then offer priority 10.
  • Due Today: offer priority 20.
Note: Recurring processing for a cycle period ends when the period ends. Network messages for usage from a an earlier period do not trigger recurring processing in the current period. Recurring processing failure on a purchased item cycle that specifies "continue after a failure" is false stops other purchased item cycles but does not stop recurring processing for balance cycles or billing cycles. If multiple offers with the same purchased item cycle are associated with grace period profiles, when recurring processing fails for the first offer and "continue after failure" is false, recurring processing stops. If the offers are associated with grace period profiles, only the first offer transitions to the grace status. The other offers have not run recurring processing, and there is no status transition for those offers.

For more information about balance, billing, and purchased item cycle processing, see the discussion about cycle processing.

Recurring Processing Failure Notifications

Configure balance templates, billing profile templates, and product offer cycle data in My MATRIXX to reference a notification profile that defines when notifications are sent after recurring processing fails (the failure to apply recurring charges). Notifications include the following information:
  • If the failure was for a balance cycle, billing cycle, or purchased item cycle.
  • If the failure was for a balance cycle, the balance template ID, and the balance resource ID.
  • The OID and external ID of the purchased item owner.
  • If the failure was for a purchased item cycle, the resource ID of the purchased item, the catalog item ID of the purchased item, and the external ID of the catalog item.
  • The start time and end time of the cycle period for which recurring processing failed.
  • An estimate of recurring charges and grants (advice of charge) for the cycle.
    Note: This information can be used to determine the amount of a balance recharge or payment. Credit limits of currency balances are ignored, and balances are not updated in the database. If recurring processing fails due to insufficient funds in a pseudo-currency balance or an asset balance, no estimate is provided. The advice of charge information is included in the MtxNotification balance impact fields.
Note: If a purchased item is in a recoverable state when recurring processing fails, a recurring failure notification and event are not generated.

Each recurring processing failure notification profile can be configured to send a notification upon a failure and multiple notifications (minutes, hours, days, weeks, months, or years) relative to the time of the initial recurring failure for the period in which the failure occurs. If the balance instance is periodic, a balance expiration notification is triggered when the instance expires and when each individual entry in the instance expires.

If a recurring failure notification profile is defined on an event and the offer fails, a recurring failure notification is sent for the initial recurring failure. If you do not define the profile to send multiple notifications, later recurring failures within the same cycle do not generate a notification.
Note: Recurring processing failure notifications stop when recurring processing is successful. If recurring processing succeeds (for example, due to a product offer purchase) after a failure and before the time to generate the notification, the notification is not generated. For example, if the recurring failure event is set to be five minutes after the event, and recurring processing succeeds before the notification is scheduled to be sent, no failure notification is sent.

For more information about configuring balance templates, billing profile templates, and notification profiles, see My MATRIXX Help.

Recurring Failure Events

When a recurring operation fails due to insufficient funds, the system does not raise an exception or cancel the operation. Instead, it logs a message and continues running. MATRIXX Engine can retry the recurring operation a configured number of times and track the number of recurring failures. Recurring errors must be resolved before the next recurring period.

An MtxRecurringFailureEvent EDR is generated during purchase or resume if recurring failure is allowed and recurring processing fails. The EDR includes detailed information about the purchased item with failed cycle renewal fields: OfferInfoArray and BundleInfoArray. When an offer or bundle belongs to a purchase package, only the immediate items that are part of the purchase package are listed in the event. For example, if a purchase package contains an offer and a bundle, only that offer and bundle are listed, not the offers that are part of the bundle. For more information, see the discussions on event generation for failed transactions, operation types, and event types. For more information about MtxRecurringFailureEvent, see the discussion about MtxRecurringFailureEvent in MATRIXX Integration.

Status Life Cycles

Use the MtxStatusConditionRecurringFailure condition to configure a subscriber or group status life cycle to transition after a billing cycle, balance cycle, or purchased item recurring processing failure. The transition can be delayed by a configured amount of time relative to the time of the initial recurring failure for the period. For balance cycles, you can specify a balance class and, optionally, a balance template in the condition. The condition is triggered if recurring processing fails for any balance of the specified balance class or for the specific balance template.

For more information about the status life cycles, see the discussion in status life cycles in MATRIXX Subscriber Management API. For more information about configuring status life cycles, see the discussion in status life cycles in My MATRIXX Help.