Rules for Balance Time Adjustments and Top-ups

The SubMan balance adjustment and top-up APIs can be used to change the start and end time of a balance or meter.

The following rules apply to start time adjustments.
  • Start time adjustments only apply to simple and periodic G/L balances in a subscriber or group wallet. They do not apply to virtual balances.
  • When the start time of a periodic balance is adjusted, the change is applied to the entire periodic balance and not to an individual balance interval.
  • The start time is valid if it is earlier that the currently configured start time.
  • The new start time must be an absolute value. You cannot change it to be relative to the adjustment request time or the current start time.
  • When the start time of a periodic balance is changed, it applies to the entire periodic balance, and not to an individual balance interval.
  • The start time of an expired simple balance can be changed, but not an expired periodic balance.
  • When extending the start time of an aggregated G/L balance, the start time of all aggregated balances above it will be extended if they are later than the new end time.
  • Notifications are not sent when a balance start time is changed.

The following rules apply to end time adjustments.

  • The End Date Adjustment Type value in the balance definition must be set to Allow to be able to extend the end date or end time using the SubMan APIs.
  • End time adjustments only apply to simple and periodic G/L balances in a subscriber or group wallet. They do not apply to virtual balances.
  • When the end time of a periodic balance is adjusted, the change is applied to the entire periodic balance and not to an individual balance interval.
  • The end time is valid if it is later than the currently configured start time and the time of the adjustment event. Note that the specified end time can be earlier or later than the currently configured end time as long as it meets the validity criteria.
  • You can set the EndTime or the EndTimeExtensionOffset. If you try to set both, an error is returned.
  • You can configure the system to allow the balance end time of a simple or periodic G/L balance to be set in the past by answering y to the following create_config.info question: GLOBAL:Should a manual balance adjustment allow the end time be set in the past (y/n)?
    • The end time cannot be later than the current time (now) if you have answered n to the configuration question.
    • The end time cannot be later than the current time (now) if you have answered y to the configuration question, and you have attempted to set a balance in the past that is not a simple or periodic balance.

    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.

  • On-demand and aggregated balances can have their end time extended into the future but not into the past.
  • The end time can be an absolute value, such as 4 weeks. You cannot set the end time in the past using a relative value.
  • The end time of an expired simple balance can be changed, but not an expired periodic balance.
  • When extending the end time of an aggregated G/L balance, the end time of all aggregated balances above it will be extended if they are earlier than the new end time. Virtual balances above and below it in the hierarchy are adjusted.
  • Notifications are not sent when a balance end time is changed.
Note: These are not the same rules that apply when adjusting the balance end time during catalog item purchases, which is implemented by using balance state update components.
Attention: For a balance adjustment to succeed, the balance start and end times must be valid at the time the API call is made.