Recurring Processing Grace Periods

Using Grace Period Profiles to Deactivate Purchased Product Offers

By default, product offers do not have grace period profiles, which means they are active indefinitely. The MtxStatusPolicyOfferRating setting controls whether usage rating is allowed when a purchased item is in a specific offer state. If recurring processing fails and the purchased item transitions to a grace or a recoverable state, the purchased item is eligible for usage if MtxStatusPolicyOfferRating is enabled for the grace or recoverable state. You use grace period profiles to specify when to transition a product offer to an inactive state so that it cannot be returned to active status. The grace period profiles use the grace period count, and recoverable period count timers to do this.

The grace period count determines how long MATRIXX Charging Application allows a subscriber to once again use the purchased item on the same purchased item cycle. The purchase item has a grace status during the grace period. Recoverable periods do the same thing, but also allow you to set a new purchased item cycle for purchased item use. The product offer has a recoverable status during the recoverable count. You create grace periods and recoverable periods in grace period profiles using My MATRIXX.

Grace period profile behavior depends on the combination of the grace period count and recoverable period count. This is how they work together:

By default, product offers do not have a grace period or recoverable period. The product offer remains in an active state and the cycle period remains the same. The subscriber may restart product offer usage any time that recurring processing succeeds.
If a grace period count is set, but no recoverable period is set, the purchased item is set to an inactive state when the grace period count ends.
Recoverable periods are used in addition to a grace period count, and they start immediately after the grace period ends. Recoverable periods also allow subscribers to restart product usage, but on a new purchased item cycle.
If the grace period ends and recurring processing has not succeeded, the cycle holding balance is forfeited. For information about cycle holding balances, see the discussion about cycle holding balances in MATRIXX Pricing and Rating.

How the cycle period is impacted by the profile count and recoverable count depends on how long the counts are:

If only a grace count is configured, regardless of whether it is longer than the cycle period, the purchased item is returned to use on the same cycle that it originally had.
If only a recovery count is configured, regardless of whether it is longer than the cycle period, the purchased item is returned to use on a new cycle that you set in the recoverable period.
If both grace and recoverable counts are configured, the grace count is used first, followed by the recoverable count. Combined they might be longer than the cycle period; this cycle period is determined by either successful recurring processing in the grace count or successful recurring processing in the recoverable count. If within the grace count, processing continues on the original cycle; if within the recoverable count, the new cycle defined in the recoverable period is used.

When an offer with a purchased item cycle and periodic balance exits a recoverable period, a balance period is created to cover the elapsed time between the original cycle start date/time and updated cycle start date/time. In situations where there is rollover you must account for possible additional periods. In this situation, consider defining an extra period in the balance array. The following example demonstrates what happens to a periodic prepaid balance when an offer enters recovery. The columns in the example are:

Start date/time.
End date/time.
Gross amount, for example, -31457280.
Credit limit, for example, 0.

2021-09-26T21:26:39+07:00 N/A
2021-09-26T21:26:39+07:00 2021-09-26T21:27:45+07:00       -31457280          0
2021-09-26T21:27:45+07:00 2021-10-26T21:27:45+07:00               0          0
2021-10-26T21:27:45+07:00 2021-11-26T21:27:45+07:00               0          0

This example shows a prepaid balance of -31457280. A prepaid balance is represented as a negative gross amount and has a credit limit of 0. This prepaid balance is for the period from start date/time 2021-09-26T21:26:39+07:00 to end date/time 2021-09-26T21:27:45+07:00.

The next example shows when the offer exits recovery:

2021-09-26T21:26:39+07:00 N/A
2021-09-26T21:27:45+07:00 2021-09-26T21:32:57+07:00               0          0
2021-09-26T21:32:57+07:00 2021-10-26T21:32:57+07:00       -31457280          0
2021-10-26T21:32:57+07:00 2021-11-26T21:32:57+07:00               0          0

In this example, the purchased item is out of recoverable state. The first period has the start time 2021-09-26T21:27:45+07:00 and end time 2021-09-26T21:32:57+07:00. This extra period is created when exiting a recoverable state. The period from start time 2021-09-26T21:32:57+07:00 to end time 2021-10-26T21:32:57+07:00 is now in effect.

Using Grace and Recoverable Periods shows how to use grace period counts and recoverable counts to affect a purchased item life cycle and recurring processing cycle period. In this case the purchased item is a product offer. This table assumes that recurring processing has already failed, and MATRIXX Charging Application is using the counts to determine when to invalidate the purchased item. A purchased item expires when its status is set to Inactive, and it cannot be used again (cannot be set to Active). The top row shows the default behavior, with no grace period profile configured.

Table 1. Using Grace and Recoverable Periods
Product Offer/Purchased Item Cycle Behavior	Grace Period Count	Recoverable Period Count
Offer never expires. Cycle never changes.	N/A. No Grace Period Profile.	N/A. No Grace Period Profile
Offer never expires. Cycle changes when recurring processing is successful.	None.	Set recoverable count to a long period (many years). Specify new cycle in Renew Time Type Field.
Offer can be revalidated within X days and retain the same cycle. Offer is revalidated if recurring processing is successful within X days. Offer expires if recurring processing is not successful within X days.	Set grace count to X days.	None.
Offer can be revalidated and retain it's cycle within X days. After X days, the offer can be revalidated and get a new cycle within Y days. Product offer expires if successful recurring processing does not happen within X + Y days.	Set grace count to X days.	Set to recoverable count to Y days. Specify new cycle in Renew Time Type Field.
Offer expires after Y days. Cycle changes if recurring processing is successful.	None	Set the recoverable count to Y days. Specify a new cycle in the Renew Time Type field.

Grace Period Counts

The grace period count can be set to any time that makes sense for your MATRIXX environment. The grace period start time depends on the processing type:

Renewal recurring processing — The grace period start time is the cycle start time. If processing fails in the middle of a product cycle, the grace period still starts at the start of the cycle start time. This is true even the failure is delayed until the cycle start time has passed. For example, if the cycle start time is 00:00:00, and recurring processing occurs at 00:15:10 and it fails, the grace period still starts at 00:00:00.
Prorated recurring processing during purchase — The grace period starts at the time processing fails. If processing fails in the middle of a recurring processing cycle, the grace period count remains unchanged. This might happen if the subscriber purchased another offer and aligned the processing cycle to an existing offer. If the grace period count is set to a month, and processing fails on in the middle of the month, the subscriber still has a full month after the failure date to try to run processing and start using the product offer again on the same purchased item cycle.

This example shows a typical use for a grace period: A product offer has a purchased item cycle of 30 days and renewal time of April 1. Recurring processing fails on April 1 and the purchased item enters into a 20-day grace period. On day 15 of the grace period, recurring processing succeeds and the cycle resumes and begins again on April 1.

Note: Purchased item cycles aligned to a master purchased item cycle ("dependent" purchased item cycles) use the grace period profile of the master purchased item cycle. The master purchased item cycle/dependent purchased item cycle alignment is severed when either item is transitioned to a recoverable or inactive state.

If a previously dependent purchased item was using a grace period profile, it keeps using that grace period profile until it becomes active again.

If a previously dependent purchased item inherits the grace period profile of a master cycle, and:

That master transitions to a recoverable or inactive state, and
The previously dependent cycle becomes the target of another purchased item cycle's alignment before transitioning to active, recoverable, or inactive.

Then the newly dependent purchased item cycle uses the grace period profile settings of the new master purchased item cycle. However, it does not inherit the master's grace period profile settings until it transitions back to active.

Note: You cannot align a purchased item cycle to a purchased item that is in a recoverable state.

For information about creating grace period profiles in subscription product offers in My MATRIXX, see the discussion about subscription product offers in My MATRIXX Help.

Recoverable Period Counts

Like grace period counts, during recoverable periods the MATRIXX Charging Application continues to try recurring processing. At this time the product offer has a recoverable state. However, if recurring processing succeeds the subscriber is billed using a new cycle that you specify in the recoverable period. Recoverable periods are usually configured to be with a grace period count, and they start after the grace period count has expired. If recurring processing succeeds during the recoverable period, the cycle is re-established based on either the current time or a pre-configured time as specified by the Recoverable Period Renew Time Type property in the grace period profile. The options are:

None (which aligns to midnight)
Recovery Time
Absolute

Note: If you set this value to absolute value, the following is true:

If the purchased item cycle in recovery is monthly, the recovery time is specified as 12:00, and the charges succeed on 12/13 11:59, the initial cycle period is from 11/13 12:00 to 12/13 12:00. If there is no proration, there will be two recurring events with charges/grants/and so forth by 12/12 12:00.
If the purchased item cycle in recovery is monthly, the recovery time is specified as 12:00, and the charges succeed on 12/13 12:01, the cycle is from 12/13 12:00 to 1/13 12:00.
For more information about how proration settings might affect the recovery cycle, see the discussion about pricing proration.

Notifications for Grace Period Profiles

You can configure a grace period profile so that MATRIXX Engine sends a notification (MtxOfferTransitionToRecoverableNotification or MtxBundleTransitionToRecoverableNotification) when a purchased item enters a recoverable period and a notification (MtxOfferTransitionToInactiveNotification or MtxBundleTransitionToInactiveNotification) when a purchased item becomes inactive. Notifications are published on entry into the final state across a single operation (some states are not configured for a grace period profile). When a purchased item transitions to an inactive state due to a grace period life cycle transition, an event (MtxPurchasedItemTransitionToInactiveEvent) is generated.

Figure 1 shows a purchased item life cycle with grace and recoverable states.

A product offer life cycle with transitions from active to grace and grace to recoverable when recurring processing fails — Figure 1. Purchased Item Life Cycle