Purchasing Bundles

Bundle versions can be purchased as catalog items for a subscriber, group, or device and can be configured to trigger a purchase notification. When a bundle is purchased, all product offers in the bundle can be used for rating and policy decisions.

Note: To create a purchase charge for a bundle, a separate product offer that includes the charge must be part of the bundle. When a bundle is purchased, purchase data is stored with the bundle and not with the individual product offers in the bundle. For more information about Event Detail Records (EDRs), see the discussion about EDR contents in MATRIXX Integration.

When a bundle is purchased, one rating validity period is defined for the bundle and all product offers in the bundle expire at the same time. For more information about product offer validity periods, see the related topic about product offer validity periods.

When adding product offers to a bundle, a specific version of each product offer must be specified. Different revisions of a bundle version can reference different versions of a product offer.

When purchased for a subscriber or group, all product offers in the bundle are available to all devices associated with the subscriber or group. When purchased for a specific device, the product offers in the bundle are available only for that device.

When a bundle is purchased, all product offers in the bundle are added to the subscriber or group and all required balances and meters are added to the subscriber or group wallet. For all product offers in the bundle that contain a balance state update component, the end time of the identified balance is modified accordingly.
Note: Detailed balance information is included in the notification when a balance is updated as the result of a bundle purchase. For more information about notifications, see the discussion about notifications in MATRIXX Integration.
In addition, the following operations occur identically to product offers purchased individually.
  1. For subscription product offers already owned, if recurring pricing is pending for any recurring cycles, they are applied. Pending recurring grants are applied after all charges and discounts.
  2. Purchase price components are applied. Purchase grants are applied after all charges and discounts.
  3. For subscription offers, any recurring price components in the product offers are applied. Recurring grants are also applied after any charges, discounts, and meters. If the product offers have 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.
  4. If the product offers have scaled proration set for recurring price components, any discounts included are not prorated but are applied to the charges after they have been prorated.
Important: If a bundle includes override bundle components for any of its offers, then the price components within each offer for the same application as the bundle component are not applied. The bundle component is used instead (the bundle component overrides the offer price component). For recurring and first-use bundle components, overrides apply only to the same cycle (recurring) or balance (first-use). For more information about bundle components, see the related topic about bundle components.

Bundles can include Attr field values that extend the base bundle. For example, a bundle could be customized to include custom purchase offer parameters such as a recharge amount, an offer price override, an offer code, a discount percentage, and locale. For more information, see the discussion about working with custom MDCs in MATRIXX Subscriber Management API.

To extend a purchased item that represents a bundle at purchase time, use the MtxPurchasedOfferExtension MDC.

Note: Custom purchase data is recorded for the entire bundle, not for each individual product offer. Bundles are identified by the OfferType (2 = purchased_bundle). For more information about the SubMan APIs and the subscriber query fields, see MATRIXX Subscriber Management API.
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.