Purchasing Product Offers

Product Offer versions can be purchased as catalog items for a subscriber, group, or device and can be configured to trigger a notification to be sent at purchase time.

By default, when a catalog item is purchased, the purchased item state is active. An Event Detail Record (EDR) with AppliedCatalogItemArray, such as usage EDRs, includes the ActivationTime (when the purchased catalog item was activated) and the EndTime (when the purchased catalog item stops being valid). Catalog items can also be purchased in pre-active or pending activation state. For information about pre-active and pending activation, see the discussions about pre-active purchased items and pending activation purchased items in MATRIXX Subscriber Management. For information about EDRs, see the discussion about MATRIXX Event Detail Records in MATRIXX Integration.

When a product offer is purchased, it is added to a subscription or group and all required balances and meters are added to the subscription or group wallet. Detailed balance information is included in the notification when a balance is updated as the result of an offer purchase. For more information about notifications, see the discussion about the Notification Framework in MATRIXX Integration.
Note: A group cannot purchase an offer or bundle that includes a balance amount meter. For information about balance amount meters, see the discussion about balance amount meters in MATRIXX Pricing and Rating.
The following create_config.py questions enforce the maximum number of purchased offers and balances when product offers and bundles are purchased.
  • Global:What is the maximum number of purchased offers a subscriber, group or device could have?

    The default is 100.

  • Global:What is the maximum number of balances a subscriber or group could have in the wallet?

    The default is 200.

These limits are not enforced when purchased offers are activated. However, if the maximum number of balances per wallet limit is exceeded due to activation, then you cannot purchase product offers or bundles for the subscriber or group until you fix the issue. For more information about global configuration, see the discussion about global system configuration in MATRIXX Configuration.

When the product offer is purchased, the following operations occur:

  1. If the product offer has a balance state update component, the end time of the balance identified is modified accordingly.
  2. For subscription offers, if recurring pricing is pending for any recurring cycles, they are applied. Pending recurring grants are applied after all charges and discounts. This is for product offers already owned by the subscription or group.
  3. Purchase price components are applied. Purchase grants are applied after all charges and discounts.
    Note: If a product offer payment method is configured to use Pay Now, the normal processing of the purchase is suspended, and the Charging Server sends a payment authorization request message to the Payment Service through the ActiveMQ Gateway.
  4. For a Pay Now product offer purchase, if the authorization succeeds, the purchase is completed and a response is sent to the client that initiated the purchase.

    For more information about Pay Now, see MATRIXX Pay Now.

  5. For subscription offers, recurring pricing components for the purchased product offer are applied if they are included in the product offer. Recurring grants are also applied after any charges, discounts, and meters. If the product offer has scaled proration set for recurring price components, the charge and grant amounts applied are calculated based on the ratio of the total number of time units in the cycle and the number of time units into the cycle the product offer was purchased.
  6. If a product offer has scaled proration set for recurring price components, any discounts included are not prorated but applied to the charges after they have been prorated.
  7. For finance and service contract offers, price components include charges and discounts only.

During rating, if a product offer has recurring or first-use pricing, and the product offer has a required balance that matches the balance template associated with the pricing, only the balance instance identified as the required balance triggers the pricing (not all balance instances in the wallet that are from the same template). If a product offer has grants, and the product offer has a required balance that matches the balance template associated with the grant, the grant impacts only the balance instance identified as the required balance (not all balance instances in the wallet that are from the same template). If a product offer does not have any required balances identified, then any recurring and first-use pricing is applied to all compatible balance instances. If there are grants, they are applied to the balance instance that expires last.

When a catalog item is purchased or resumed using the SubMan APIs, if there are pending recurring payments to be processed and insufficient funds to charge the payments, the response includes the ResultCode CREDIT_LIMIT_REACHED (38) and ResultText "Insufficient funds for recurring charges…". For more information about SubMan API result codes, see the discussion about result codes in MATRIXX Subscriber Management API.

Important: When a device, subscription, or group purchases a product offer with one or more required tier balances, the Charging Server determines if the set of required tiers are all present in only one group hierarchy. If it is not, the purchase fails. New balances are updated or new balances are created at the required tiers as determined by the balance instance creation policy defined for the balance templates.
When purchasing and canceling catalog items using the SubMan APIs, the SubMan API responses and notifications include a list of updated balances with the following information:
  • Balance ID
  • Owner ID
  • Balance validity
  • Type of balance (main balance, actual currency balance, or cost balance)
  • Total updated amount
  • Current amount
  • A list of update amounts and the update types:
    • 1 — Charge
    • 2 — Discount
    • 3 — Grant
    • 4 — Adjustment
    • 5 — Cancellation Refund
    • 6 — Cancellation Forfeiture
    • 7 — Forfeiture
    • 8 — Usage Refund
    • 9 — Transfer To
    • 10 — Transfer From
    • 11 — Rollover To
    • 12 — Rollover From
    • 13 — Payment
    • 14 — Tax
    • 15 — Cancellation Tax Refund
    • 16 — Usage Tax Refund
    • 17 — Recharge
    • 18 — Payment Refund
    • 19 — Late Charge
    • 20 — Early Termination Charge
    • 21 — Write-Off
    • 22 — Finance
    • 23 — Debt Payment
    • 25 — Tax Payment
    • 26 — Payment Tax Refund
    • 27 — Tax Paid Previously
To prevent bill shock, the PurchaseOffer and CancelOffer SubMan APIs can be called in advice mode (Advice of Charge) to estimate the cost of the purchase or cancelation. Response APIs describes the response SubMan APIs.
Table 1. Response APIs
Response Description
PurchaseOffer APIs When a PurchaseOffer SubMan API is called in advice mode, the response includes estimates for the purchase cost (charge and tax), any recurring charges, the amounts of granted assets, the cost of financing for a given down payment, including the principal amount financed, and the amount and number of installments in the finance contract offer.
CancelOffer APIs When a CancelOffer SubMan API is called in advice mode, the response includes estimates for the cancelation cost (charge and tax), the amount of the refund for any recurring charges, the amounts of forfeited assets, or the early termination charges in the finance contract.
Note: A catalog item purchase is not the same as a purchase made by a subscriber while using a service. Catalog item purchases are associated with non-usage pricing and service-based purchases are associated with usage pricing. For example, when a subscriber purchases additional minutes for a minutes balance, the purchase does not occur during service usage, so non-usage-based pricing is applied. In contrast, when a subscriber is using a data service to purchase a song or application, the purchase occurs while using the data service, so usage-based pricing is applied.