Purchasing Catalog Items

When a subscription or group purchases a catalog item, it is added to the list of catalog items owned by that subscription or group, and all necessary balances are added to the owner's wallet.

When a group purchases a catalog item, the G/L balance is added to the group wallet, and the required virtual balances are added to group-member wallets.

When purchasing catalog items, you can set fields such as the StartTime, EndTime, EndTimeRelativeOffset, and Attr.
Important: The StartTime, EndTime, and EndTimeRelativeOffset values specified in the REST APIs take precedence over the pricing-defined policy parameters. For an example of a REST call that specifies an EndTimeRelativeOffset value, see the SubscriberPurchaseOffer discussion in the related references.

Start Times

The StartTime value in MtxPurchasedOfferData sets when the catalog item is valid for use. The StartTime must be before or the same as the current time. The offer start type policy configured in the subscription product offer template in My MATRIXX includes the following options:
  • Specified at Purchase — Allows service representatives to specify a start time for the product offer when they purchase it for a subscription or group.
    Important: If a start time is not set, the offer is valid as per the Offer Start Type (the default value is 'none'). If a start time is set, it must be before or the same as the purchase time. Specifying a future start time generates an error during rating.
  • Purchase Time — The product offer becomes valid for rating immediately when it is purchased. If it is not specified, the Offer Start Type defaults to 'none'. In such cases, all purchase operations occur immediately, such as associating the purchased product offer with the subscription or group, adding necessary balances to the wallet, applying pricing, and sending a purchase notification, if configured.
  • Absolute — The product offer becomes valid on the specified date/time. You must specify the month, day, and year and may specify a time of day in Start Date/Time. If a time of day is not specified, the product offer becomes valid at 12:00:00 AM on the specified date.
    Note: If the absolute date is in the future, any attempted purchase of that offer fails until the offer becomes valid.

End Times

The EndTime value and EndTimeRelativeOffset values in MtxPurchasedOfferData set when the catalog item is no longer valid for use. You can set one or the other, but not both. The EndTime value sets an absolute date/time. The EndTimeRelativeOffset value sets a number of units, and EndTimeRelativeOffsetUnit sets a unit type. The EndTimeRelativeOffset and EndTimeRelativeOffsetUnit together define the amount of time a catalog item is valid after it is purchased. When you specify the EndTimeRelativeOffsetUnit and EndTimeRelativeOffset, the calculated EndTime of the purchased item is relative to the purchase or activation time. If EndTime, EndTimeRelativeOffsetUnit, and EndTimeRelativeOffset are not specified in MtxPurchasedOfferData. The EndType policies are used to calculate the EndTime.

The time of day value of the EndTime of an independent purchased item is the same as the CycleStartTime (time of day) of the purchased item cycle if:
  • The purchased item cycle definition has a purchase date CycleOffsetType and a CycleStartTime (time of day).
  • The EndTime of the purchased item is relative to the purchase date/time.
  • The EndTimeRelativeOffsetUnit of the purchased item is the same as the PeriodType of the purchased item cycle (for example, both are monthly).
Supported offset units include:
  • 1: Hours
  • 2: Days
  • 3: Weeks
  • 4: Months
  • 5: Years
  • 6: Billing cycle inclusive
  • 7: Billing cycle exclusive
  • 8: Minutes
The offer end type policy configured in the subscription product offer template in My MATRIXX includes the following options:
  • None — The product offer end date is set to the maximum end date, which is effectively no end date. If this field is set to None, the end date can be set explicitly in the offer purchase call.
  • Purchase Relative — (Not applicable to global offers) The product offer becomes invalid after an amount of time relative to the purchase date.
    If you select this option, in Ends in, specify a positive integer indicating the offset from the purchase date and select one of the following offset units:
    • Minutes
    • Hours
    • Days
    • Weeks
    • Months
    • Years
    • Billing Cycle Inclusive — The offer end time is calculated as n cycles after the start of this cycle. The end time of the current billing cycle is included as the end of one elapsed billing cycle.
    • Billing Cycle Exclusive — The offer end time is calculated as n cycles after the end of this cycle. The current billing cycle is not included in the specified number of elapsed billing cycles.

      Billing Cycle Inclusive and Billing Cycle Exclusive set the end time of the purchased offer to the end time of a specified number of elapsed billing cycles. The bill cycle length is fixed at purchase time and does not change if a billing cycle is modified.

  • Start Relative — (Not applicable to global offers) The product offer becomes invalid after an amount of time relative to the start date.
    If you select this option, in Ends in, specify a positive integer indicating the offset from the start date and select one of the following offset units:
    • Minutes
    • Hours
    • Days
    • Weeks
    • Months
    • Years
    • Billing Cycle Inclusive — The offer end time is calculated as n cycles after the start of this cycle. The end time of the current billing cycle is included as the end of one elapsed billing cycle. The bill cycle length is fixed at purchase time and does not change if a billing cycle is modified.
    • Billing Cycle Exclusive — The offer end time is calculated as n cycles after the end of this cycle. The current billing cycle is not included in the specified number of elapsed billing cycles. The bill cycle length is fixed at purchase time and does not change if a billing cycle is modified.

      Billing Cycle Inclusive and Billing Cycle Exclusive set the end time of the purchased offer to the end time of a specified number of elapsed billing cycles. The bill cycle length is fixed at purchase time and does not change if a billing cycle is modified.

  • Absolute — The product offer becomes invalid on the specific date/time you set in End Date/Time.
  • Absolute and Purchase Relative — (Not applicable to global offers) The product offer becomes invalid on the absolute date you set in End Date/Time or the purchase-relative date you set in Ends in, depending on which one comes first.
  • Absolute and Start Relative — (Not applicable to global offers) The product offer becomes invalid on the absolute date you set in End Date/Time or the start-relative date you set in Ends in, depending on which one comes first.
  • Cycle Count — The offer ends in the number of cycles specified in Ends in. To select Cycle Count, you must first select a Period Type on the Cycle Data tab.

Custom Parameters

The Attr field values specified in MtxPurchasedOfferData extend the base catalog item. For example, a purchased catalog item can be customized to include custom parameters such as a recharge amount, price override, custom code, discount percentage, and locale. For more information about Attr field values, see the discussion about extending data objects in MATRIXX Subscriber Management API.