Pending Activation Purchased Items

When purchasing a catalog item, you can specify that pending activation is allowed when there are enough funds for the purchase charge but not enough funds for activation and recurring charges.

In this situation, the purchased item is in pre-active state until there are enough funds for the activation and recurring charges. When all the required charges are paid, the purchased item transitions to active state. There must be enough credit in the balance for the activation and recurring charges within the specified time period or the purchased item is canceled. If the catalog item is a bundle, all product offers in the bundle are processed as a unit; the bundle and all its child offers have the same offer status.

SubMan APIs

To allow pending activation, you must set the IsPendingActivationAllowed field in MtxPurchasedOfferData in the PurchaseOffer APIs. When true, the catalog item can be purchased in pre-active state if there are enough funds for the purchase charge but not enough for the activation and recurring charges.

When IsPendingActivationAllowed is true, you must also set the following fields in the MtxPurchasedOfferData in the PurchaseOffer API:
  • ActivationExpirationTime — Sets the absolute date and time of activation expiration. You can set the ActivationExpirationTime or the ActivationExpirationRelativeOffset, but not both.
  • ActivationExpirationRelativeOffsetUnit — Sets the type of units for ActivationExpirationRelativeOffset. Values are:
    • 1 = hours
    • 2 = days
    • 3 = weeks
    • 4 = months
    • 5 = years
    • 6 = billing_cycle_inclusive (including current billing cycle)
    • 7 = billing_cycle_exclusive (excluding current billing cycle)
    • 8 = minutes.
  • ActivationExpirationRelativeOffset — Sets the number of units relative to the offer purchase time to set the activation expiration time. You can set the ActivationExpirationTime or the ActivationExpirationRelativeOffset, but not both.
Note: If IsPendingActivationAllowed is true, the pre-active purchase related parameters PreActiveState, AutoActivationTime, AutoActivationRelativeOffsetUnit, AutoActivationRelativeOffset, and AutoActivationCycleResourceId are not applicable and the PurchaseOffer API request will return a validation error if they are specified.
If IsPendingActivationAllowed is true, the SubMan API request returns a validation error in the following situations:
  • The IsRecurringFailureAllowed parameter is also true when calling the PurchaseOffer API.
  • In the My MATRIXX cycle data configuration, if IsRecurringFailureAllowed is selected for a product offer or bundle.
  • The product offer is a one-time offer or it has ActivateWithUsage enabled.
  • A catalog item has a purchase state of active or pre-active.

The MtxPurchaseInfo in the purchase response includes the offer status and offer life cycle profile.

The IsPendingActivation field in the MtxPurchasedOfferInfo MDC indicates whether the purchased item was purchased in a pre-active state because IsPendingActivationAllowed was true and there were not enough funds for the activation and recurring charges.

Offer Life Cycle Status

When purchasing a product offer, you can specify the initial offer status of the purchased item by setting the OfferStatusValue (UINT16) field in the MtxPurchasedOfferData MDC. If you do not set the OfferStatusValue, the initial offer status is the default offer status for class_active (or the default offer status for class_pre_active for pre-active purchases) as defined in the offer life cycle profile. The specified initial status must be a class_active status if IsPendingActivationAllowed is true.

If there are enough funds for the purchase charge but not enough funds for activation and recurring charges, the default class_pre_active offer status in the offer life cycle profile will be the initial offer status of the purchased item. For more information about offer life cycles, see the discussion about offer life cycle profiles in MATRIXX Subscriber Management API.

Processing Order

If multiple catalog items are purchased in a PurchaseOffer API request, the catalog items are processed in the same order as specified in the OfferRequestArray parameter. When processing each catalog item, if the purchase, activation, and recurring charges can be paid, the item will be purchased in active state; otherwise, if IsPendingActivationAllowed is true and the purchase charge can be paid, the item will be purchased in pre-active state. Then the next catalog item will be processed. If the purchase charge cannot be paid for a catalog item, the purchase operation returns an error and no catalog item is purchased.

An MtxPurchaseEvent EDR is generated if the purchase is successful. The EDR includes the offer status, offer life cycle profile ID, and a pending activation flag. For more information about the MtxPurchaseEvent EDR, see the discussion about EDRs in MATRIXX Integration.

Notifications

An MtxOfferPurchaseNotification or MtxBundlePurchaseNotification is generated if the purchase is successful. The notification includes the activation expiration time and pending activation and recurring charges. For more information about notifications see the discussion about notifications in MATRIXX Integration.

Purchased Item Suspend and Resume

Pending activation purchased items are in pre-active state and can be suspended and resumed if the suspend policy is enabled in the offer status definition in the offer life cycle profile. Recurring processing is disabled for suspended purchased items. Therefore, suspended pre-active purchased items cannot be activated. For more information about suspending and resuming purchased items, see the discussion about suspend and resume in MATRIXX Subscriber Management API.

Purchased Item Activation

Before the activation expiration time is reached, when a recharge, top-up, or balance adjustment operation creates enough credit in the balance for the pending activation and recurring charges, the pre-active purchased item is activated and transitioned to active state.

Pending activation purchased items are processed by resource ID (the purchase time). MATRIXX Engine processes each item in the purchased offer array and attempts to activate it if it is a pending activation purchased item.

MATRIXX Engine generates MtxPurchasedItemActivationEvent and MtxPurchasedItemStatusChangeEvent EDRs and an MtxPurchasedItemStatusChangeNotification message.

For more information about purchased item activation, see the discussion about purchased item activation in MATRIXX Subscriber Management.

Purchased Item Activation Expiration

If the pending activation and recurring charges are not paid when the activation expiration time is reached, the pre-active purchased item is canceled and purged. When cancelling the offer, cancel pricing components are applied. MATRIXX Engine generates a MtxCancelEvent (with a pending activation flag) and MtxPurchasedItemStatusChangeEvent EDRs.

MATRIXX Engine generates an MtxOfferCancelNotification or MtxBundleCancelNotification message and an MtxPurchasedItemStatusChangeNotification message.