Debt Balances

A debt balance tracks the debt associated with currency charges on a product offer. Debt balance is a simple, postpaid, locked, actual currency balance with unlimited credit that tracks the debt associated with currency charges in a product offer or bundle. Both the purchase and recurring debt balance must be simple balances.

A debt balance determines how an offer reacts to a currency change on a prepaid balance when the credit limit is reached. Any prepaid actual currency balance with credit can be used to pay off debt balances including recharge, top-up offer, and balance adjustments. Debt balances cannot use the subscriber or group balance adjust or top-up balance APIs: MtxRequestSubscriberTopupBalance, MtxRequestSubscriberAdjustBalance, MtxRequestGroupAdjustBalance, and MtxRequestGroupTopupBalance.

Note: A debt balance can be associated with external payment methods, allowing the debt to be paid off through an external payment request. External payment requests are generated at offer purchase time and in advance of new cycle start time. For more information about external payment methods, see the discussion about balances with external payment requests.

For information about debt balance during recharge or adjustment, see the discussion about debt balance during recharge or adjustment.

A debt balance is defined by the balance template, the debt balance type, and the write-off policy, and is specific to the catalog item being purchased. Debt balances on an offer are created at purchase/activation time, with an end time of infinity. Debt balances are not included in balance normalization.
Note: A debt balance cannot be based on a main balance template.

Upon purchase or recurring processing, the debt balance is charged based on the currency amount after the prepaid currency balances are consumed; the fee debt balance is managed independently. For information about debt balance impact when an offer is purchased or has recurring charges, see the discussion about debt balance during purchase or recurring.

Each offer or bundle is associated with a specific offer lifecycle profile. For details, see the discussion about purchased item cycle status life cycles.

For product offers in a bundle, the bundle overrides the debt balance type so that:
  • The bundle can specify a debt type not in the product offers.
  • If two or more product offers in a bundle specify the same debt balance type, a single balance instance is created.
  • Two product offers in a bundle cannot specify different balance templates for a given debt balance type.
Note: To sort debt balances by recurring processing priority, you must set the Priority in the Cycle Data tab in the product offer or bundle pricing configuration. If no priority is provided, the priority defaults to zero and debt balances are not sorted.
The three debt balance types are:
  • Fee — Grace period fee and cancel charge debt.
  • Purchase — Purchase charge debt.
  • Recurring — Recurring charge debt.
The write-off policy for debt balance can be:
  • None — No write-off.
  • Cycle — Write off debt at end of the cycle.
  • Specific time — Write off debt at a specified time.
  • Expired — Write off debts when the offer expires.
The write-off policy for each debt balance type can be:
  • Purchase — Write-off policy can be none, specific time, or expired.
  • Recurring — Write-off policy can be none, cycle, or expired.
  • Fee — Write-off policy can be none, cycle, or expired.

For information about how debt balance is written-off based on the configured write-off policy, see the discussion about debt balance and recurring write-off policy.

Debt Balances describes each debt balance type.

Table 1. Debt Balances
Debt Balance Type Description
Fee A fee debt balance is for any fee applied using the FeeCharge status action. The fee debt balance write-off policy can be none, cycle, or expired.
Purchase A purchase debt balance is purchase charge debt. The purchase debt balance write-off policy can be none, specific, or expired.
Recurring A recurring debt balance is recurring charge debt. The fee debt balance write-off policy can be none, cycle, or expired.

Write-Off Policies describes each write-off policy. When a purchase debt balance with a write-off policy of specific time is written off, the MtxPurchasedOffer.ActivationTime field can be used to calculate when the purchase debt balance is to be written off. If an offer is purchased in an active state, MtxPurchasedOffer.ActivationTime and MtxPurchasedOffer.PurchaseTime are the same value. For more information about ActivationTime and PurchaseTime, see the discussion about pre-active purchased items in MATRIXX Subscriber Management.

Table 2. Write-Off Policies
Write-Off Policy Description
None When the write-off policy is set to none, there is no write-off. An expired offer cannot be purged until all debts are paid. After a configured duration after offer expiration time, the debts are written off, and then the offer is purged.

An offer cannot be purged until all debt is paid. After a configurable duration after offer expiration time, the debt is written off and the offer is purged. The default value is 30 days.

Configure how long after an offer expires that the unpaid debt is written off by entering the number of days in the create_config.info question: Global:How long (in days) after an offer expires should the unpaid debt be written off?30

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.

Note: This is applicable for debt balances not associated with an external payment request. For more information about external payment methods, see the discussion about balances with external payment requests.
Cycle Only recurring and fee debt balances can have a write-off policy of cycle.

For a recurring debt balance, when the write-off policy is set to cycle, a recurring debt balance is written off at the end of the cycle.

For a fee debt balance with a write-off policy of cycle, when the offer expires, the fee debt balance is written off at the end of the cycle.
Specific Time Only purchase debt balances can have a write-off policy of specific time.

When selected, purchase debt is written off at the specified time. The setting specific time is the offset from the purchase or activation time, for example, two days from the time the offer was purchased or activated.
Expired When expired is selected as the write-off policy on any type of debt balance, the debt is written off when the offer expires.
Note: A debt balance can be associated with external payment methods. If a debt balance has an outstanding external payment request which is not due yet (that is, the payment due date is in the future), then the write-off policy cannot be enforced until the external payment request becomes overdue.