SubscriptionAdjustBalance

Request to adjust a balance or meter in a subscription wallet.

A business operation may require a balance to be adjusted directly (for example, due to a customer complaint or billing error). The adjust type can be:
  • 1 — Credit a balance or meter.
  • 2 — Debit a balance or meter.
  • 3 — Reset a meter.
Adjustments to a balance do not affect any meters that track charges to that balance.

You cannot adjust balance_amount and overdraft meters.

For all adjustment types, the value is always a positive amount. For adjustments to periodic balances, only the current period can be adjusted. For adjustments to virtual (aggregated) balances, the amount does not roll up to the group G/L balance. You can extend the end date to increase the length of time that adjustment is available.
Important: Balance validity times must be valid at the time of the adjustment or must be changed to be valid for all adjustment types or the balance adjustment will fail. For information about changing the start time and end time of expired simple balances, see the following Validity Time Adjustment section.
Adjustments to renewable on-demand balance periods that cause the balance to exceed its credit limit are rejected. For other balances (simple, periodic, or non-renewable on-demand) and meters, the CreditLimitPolicy field controls if a balance adjustment that causes the credit limit to be exceeded is ignored or rejected. Reservations are ignored by the CreditLimitPolicy. The CreditLimitPolicy field values are:
  • 1 — ignore
  • 2 — reject
When CreditLimitPolicy is set to ignore, the follow behavior happens during the adjustment:
  • The credit limit is disabled (so no credit limit threshold is generated).
  • The gross balance is allowed to exceed the credit limit.
  • Balance threshold components tied to the credit limit threshold are not invoked.

Validity Time Adjustment

A validity time adjustment can be a change to the start time or end time of a balance or meter instance. The time changes can be applied to simple and periodic G/L balances in a subscription or group wallet. They cannot be applied to virtual balances. When the start or end time of a periodic balance is adjusted, the change is applied to the entire periodic balance and not to an individual balance interval.
Note: Start time adjustments cannot be made to top-ups.
The following rules apply to start time adjustments.
  • Start time adjustments only apply to simple and periodic G/L balances in a subscription 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 can be changed to a time that is earlier than the configured start time but not later than it.
  • 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.
  • 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.
  • A private balance start date (StartTime) cannot be modified.
  • 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 using the SubMan APIs.
  • End time adjustments only apply to simple and periodic G/L balances in a subscription 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 can be changed to a time that is earlier or later than the current end time but must be later than the current start time and the time of the adjustment event.
  • 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 yes to the 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.
  • 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.
  • 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.
  • A private balance end date (EndTime) can be modified through the MtxRequestSubscriberTopUpBalance SubMan API.
  • Notifications are not sent when a balance end time is changed.
Note: Balance adjustments or top-ups must specify an amount with a decimal precision less than or equal to the decimal precision specified in the balance's template.

REST Example

URL 
PUT http://host:port/rsgateway/data/v3/subscription/100:56:34:56/wallet/12/adjustment
Request XML 
<MtxRequestSubscriberAdjustBalance>
   <AdjustType>1</AdjustType>
   <Amount>10.00</Amount>
   <Reason>CSAT:100</Reason>
   <Info>Customer says coupon was not applied</Info>
</MtxRequestSubscriberAdjustBalance>
Response 
<MtxResponse>
    <RouteId>1</RouteId>
    <Result>0</Result>
    <ResultText>Balance Adjusted</ResultText>
</MtxResponse>