Defining Purchased Item Cycles During Purchase

You can define cycle data for purchased item cycles in product offer and bundle templates, and if the template allows purchase-time configuration of cycle data, you can define cycle data during the purchase of a catalog item. When a purchased item's cycle is aligned to a referenced cycle (such as a balance cycle or subscriber-owned purchased item), any change to the referenced cycle results in a change to the cycle of the purchased item.

To define cycle data during the purchase of a catalog item using the REST product offer purchase and modify APIs, specify cycle parameters in MtxPurchasedItemCycleData as described in MtxPurchasedItemCycleData Fields. The SubMan APIs have additional options when defining purchased item cycles. For example, when defining a cycle type that is a balance cycle or an offer cycle, you can use the ResourceId of an offer or balance to align the purchased item cycle to.
Note: The Override Allowed property in the cycle data properties for the product offer or bundle template must be selected to specify cycle data during purchase.
When defining cycle data during purchase, you must define the CycleType. Other fields are optional or required based on the cycle type.
Note: The MtxPurchasedItemCycleData MATRIXX Data Container (MDC) has additional fields, but the ones described in MtxPurchasedItemCycleData Fields are the only allowed parameters during purchases, and the other parameters are used during modify actions. For information about restrictions on specific parameters per API, see the information about purchased item APIs in MATRIXX Subscriber Management API.
Table 1. MtxPurchasedItemCycleData Fields
Name Description
CycleType If the catalog item defines a cycle which allows purchase-time configuration, this field indicates the type of cycle this purchased item is aligned to and establishes the purchased item cycle offset and the cycle time of day if aligned to an existing cycle. The cycle types are:
  • billing_cycle (1)
  • purchase_time (2)
  • balance_cycle (3) (You must set the CycleResourceId field.)
  • offer_cycle (4) (You must set the CycleResourceId field.)
  • fixed_offset (5) (You must set the CycleOffset field.)
  • current_time (6)
  • purchase_date (7) (You must set the CycleStartTime field.)
CycleResourceId If the supplied CycleType is balance_cycle (3) or offer_cycle (4), this field indicates the ResourceId of the catalog item or balance to align the purchased item cycle to.
CycleOffset If the supplied CycleType is 5 (fixed_offset), this field is used to specify the fixed offset of the purchased item with which to initially align the purchased item cycle. Cycle offsets only apply for weekly, monthly, or yearly period types. For weekly periods, the offset values are:
  • Sunday (1)
  • Monday (2)
  • Tuesday (3)
  • Wednesday (4)
  • Thursday (5)
  • Friday (6)
  • Saturday (7)
The defined cycle offset is used as follows:
  • For a weekly cycle, the offset is the day of the week.
  • For a monthly cycle, the offset the day of the month.
  • For a yearly cycle, the offset the day of the year.

For example, if the purchased item has a monthly cycle and an offset of 15 is specified, the cycle begins on the 15th day of the month.

CycleStartTime (Optional) Used if CycleType is purchase_date.
CycleOwnerType Values are:
  • device (1)
  • subscriber (2)
  • group (3)
  • user (4)
You must set this to subscriber (2) to specify that the purchased item owner is a subscriber when the following are true:
  • The CycleType is offer_cycle (4).
  • The CycleResourceId specifies a subscriber-owned offer.
  • A device is aligning to the subscriber's purchased item.
UseTargetResource (Optional) If this parameter is set to true, the resource ID of the last purchased item evaluated with IsTargetResource set to true is used as the value of the CycleResourceId.

For information about configuring cycle data in product offer and bundle templates, see My MATRIXX Help.