Purchase Package Cycle

A purchase package defines a cycle. When a purchased item is added to the purchase package, the purchase package cycle definition overrides the cycle data of the product offer and bundle definitions in pricing.

Note: The Override Allowed setting in the product offer and bundle definitions is ignored.

The purchase package cycle is the master cycle and the purchased item cycles are aligned to the master cycle. The purchased item cycle from other purchased items not in the purchase package cannot be aligned to a purchase package cycle. The purchase package cycle cannot be aligned to the cycle of a purchased item.

When defining a purchase package in the PurchaseOffer APIs, you must define the purchase package cycle as part of the purchase package data. The cycle data consists of the period type and period interval, cycle offset type and cycle offset, and the cycle start type for recurring processing.

For more information about the PurchaseOffer APIs, see the discussions about MtxRequestSubscriberPurchaseOffer, MtxRequestGroupPurchaseOffer, and MtxRequestDevicePurchaseOffer in MATRIXX Subscriber Management API.

The cycle definition can be modified using the ModifyPurchasePackage APIs. The cycle for all purchased items in the purchase package changes when the purchase package cycle definition is modified and a purchased item cycle change event is generated. If there are balances aligned to the purchased item cycle, the balance cycles are also modified.

When the cycle definition is modified, all purchased items in the purchase package inherit the new cycle definition. If the purchase package cycle has the same period type and period interval as the billing cycle, you can use the ModifyPurchasePackage APIs to modify a purchase package cycle to align it to the billing cycle and update the cycle offset, cycle start time, cycle end time, and optionally disable the billing cycle alignment. If the cycle end time is modified, an MtxPurchasedItemCycleChangeEvent event is generated for the purchase package, and an MtxPeriodEndTimeChangeEvent event is generated for each purchased item in the purchase package. If the cycle alignment is disabled, an MtxPurchasedItemCycleChangeEvent event is generated for the purchase package.

Specify whether cycle change takes effect immediately or at the end of the current cycle period. If the change takes effect immediately, an MtxPeriodTerminationEvent or MtxPeriodEndTimeChangeEvent event is generated and any applicable refunds or forfeitures are issued. If the change is not immediate, then charge or grant proration is applied to the new cycle. For more information about modifying a purchase package, see the discussions about MtxRequestSubscriberModifyPurchasePackage, MtxRequestGroupModifyPurchasePackage, and MtxRequestDeviceModifyPurchasePackage in MATRIXX Subscriber Management API.

Catalog items must have the same period type and period interval in the cycle data definition as the period type and period interval in the purchase package cycle definition. For example, if the purchase package cycle definition is monthly (type = months and interval = 1), then only catalog items with a monthly cycle can be in the purchase package. Otherwise, the catalog items cannot be added to the purchase package.

Each purchased item in the purchase package can be independently suspended. When a suspended purchased item is resumed, its cycle remains aligned to the purchase package cycle. When adding an existing purchased item to a purchase package using the AddToPurchasePackage APIs, if the purchased item has a different cycle definition than the purchase package, the purchased item undergoes an immediate cycle change to align with the purchase package cycle. For more information about the AddToPurchasePackage APIs, see the discussions about the MtxRequestSubscriberAddToPurchasePackage, MtxRequestDeviceAddToPurchasePackage, and MtxRequestGroupAddToPurchasePackage APIs in MATRIXX Subscriber Management API.

When a purchased item is removed from a purchase package using the RemoveFromPurchasePackage APIs, the purchased item has an independent cycle based on that of the purchase package, and the purchased item is no longer processed with the purchase package during recurring processing. If the purchased item is in a grace or recoverable state at the time of removal, the grace period profile from the purchase package is used. Once the purchased item is out of a grace or recoverable state, it uses the grace period profile defined in the product offer or bundle definition when it next goes into a grace or recoverable state. For more information about the RemoveFromPurchasePackage APIs, see the discussions about the MtxRequestSubscriberRemoveFromPurchasePackage, MtxRequestGroupRemoveFromPurchasePackage, and MtxRequestDeviceRemoveFromPurchasePackage APIs in MATRIXX Subscriber Management API. For more information about purchase package grace periods, see the discussion about purchase package lifecycle and grace period.

Note: Do not use the ModifyOffer APIs to modify the cycle definition of a purchased item that is in a purchase package or an error will be returned.

When the subscriber or group time zone is changed through the ModifyOffer APIs, the CycleEndTime parameter is updated on all purchase packages owned by the subscriber or group. For more information, see the discussions about subscription modify offer and group modify offer in MATRIXX Subscriber Management API.