Periodic Balances

A periodic balance represents a sequence of intervals that are impacted during rating. Each interval is identified by an ID and is valid for a different period of time. Each interval can also contain a different amount. This is unlike simple balances where the entire balance contains one amount.

Periodic balances usually provide an asset amount to a subscriber on a recurring basis. For example, a grant can provide 50 megabytes to a subscriber on a daily basis with daily balance intervals. When usage events are processed, the balance interval used is the one that is valid for the time period and that has an available amount (below the credit limit). During processing, a valid balance interval is used before creating new intervals. When multiple valid intervals exist in a subscriber's wallet, to determine which interval to use, all existing intervals are checked, starting with the earliest period that has not expired by the usage time. Any existing intervals are examined after that. The earliest interval in the set that has an available amount is used.

The number of balance intervals and the size of the intervals is a configuration option you define during pricing configuration. Each balance interval in the same periodic balance is the same period length: hourly, daily, weekly, monthly, yearly, or aligned with the billing cycle. For example, a weekly balance cannot contain a daily balance interval and a monthly balance cannot contain a weekly or daily balance interval. The number of intervals in the periodic balance is called the balance window.

A standard periodic balance has a contiguous, non-overlapping set of intervals. A new interval automatically begins at the time the previous one ends, regardless of whether an event has occurred in the new interval. The start date and time of the first balance interval in the set specifies the date and time boundaries for all balance intervals in the series, as follows:
  • For periodic balances aligned with the bill cycle, the balance intervals have the same duration as the bill cycle.
  • For periodic balances aligned with a purchased item cycle, the balance intervals have the same duration as the purchased item cycle.
  • For all other periodic balances, the first interval start time (time of the day) is determined by the Cycle Start Type defined in the balance template. The start types are:
    • Midnight — The first interval starts at midnight. This is the default setting.
    • Absolute — The first interval starts at the time specified by the cycle time defined in the balance template.
    • Purchase Time — For required G/L balances, the first interval starts at the PurchaseTime (without the date).
  • For weekly, monthly, or yearly periodic balances, the start date of the first interval is determined by the Cycle Offset Type defined in the balance template, either Purchase Time or Fixed Offset.

When a periodic balance interval expires, the next interval in the series is created automatically and is immediately available for use. If configured, balance rollover allows an unused part of an asset balance to be used in the next interval. For more information about balance rollover, see the discussion about balance rollovers.

When a periodic balance expires, recurring processing stops for balance cycle periods beyond the period in which validity ends. When an offer is purchased to extend the validity of an expired periodic balance, recurring processing resumes. The period in which the offer is purchased will have prorated recurring charges and grants. The prorated amount is calculated according to the GrantResumeProrationType (default = scaled) and ChargeResumeProrationType (default = scaled) fields defined for product offers that have the recurring pricing components. For information about querying these fields, see the pricing query APIs in MATRIXX Subscriber Management API. For information about proration, see the discussion about pricing proration.
Note: When the end time of an expired periodic balance is extended using the AdjustBalance or TopupBalance SubMan APIs, recurring processing on the period in which the offer is purchased is not invoked.
For information about querying whether a balance is associated with an external payment method, see the pricing query APIs in MATRIXX Subscriber Management API.
Note: Refunds are not supported for balances with Create External Payment Request selected.

Periodic Balance with Fixed Offset

You can define a fixed offset to start each periodic balance interval. When the cycle offset type is fixed, the balance period starts at the given cycle offset. For example, set the fixed offset to the first day of the month so the periods are aligned with calendar months.
Note: When defining periodic or on-demand periodic balances, you cannot set the end time to the past. For more information about configuring periodic and on-demand periodic balances, see the discussion about configuring periodic balances in My MATRIXX Help.
The periods start at a fixed offset from the beginning based on the period type:
  • Weeks — Number of days into the week, represented numerically:
    • Sunday (1)
    • Monday (2)
    • Tuesday (3)
    • Wednesday (4)
    • Thursday (5)
    • Friday (6)
    • Saturday (7)
  • Months — Number of days into the month: 1-31
    Note: If the day of the month is greater than the actual number of days in the month, you can specify when the new period will start by answering the create_config.info question: Global:What policy should be used for determining the end of monthly balance/billing cycles?

    After making this change to the create_config.info question, apply the configuration change. For more information, see the discussion about applying MATRIXX Engine configuration changes in MATRIXX Installation and Upgrade.

  • Years — Number of days into the year: 1-365
    Note: January 1 is 1 and December 31 is 365. For a leap year, the last day of the year is used.
A fixed offset cannot be specified if the period type is Minutes, Hours, Days, Align with Bill Cycle, or Align with Purchased Item Cycle.

Recurring charges based on balance cycles with fixed offset will be prorated in the first cycle. For example, if a periodic balance has a cycle offset of 1 and an offer with recurring charges based on the balance cycle is purchased on March 15, then the recurring charges for the first cycle, March 1 to April 1, will be prorated.

For more information about configuring a periodic balance with fixed offset, see the discussion about configuring a periodic balance in My MATRIXX Help. For more information about configuring a periodic meter with fixed offset, see the discussion about configuring a periodic meter in My MATRIXX Help.