Optimize customer experience
Track the remaining balance of a credit or commit
Tracking the remaining balance of credits and commits helps you accurately understand account health, forecast revenue, and track assets and liabilities. It also supports providing customers with up-to-date information on their remaining balance.
Each credit or commit is associated with a ledger, which records events that change the balance of the commit or credit. Adding all of the entries in a ledger results in the remaining balance associated with that ledger. For example, there are ledger entries associated with the
access_schedule beginning, invoice deductions (drawdowns of the credit or commit corresponding to usage), and expirations.
Each ledger entry is associated with a type, an amount (which can be positive or negative), and an effective timestamp. There is one invoice deduction ledger entry for each invoice that consumes a credit or commit. The timestamp associated with invoice deduction ledger entries is always the end of the service period associated with the usage invoice. Use the timestamp to show customers their remaining balance including pending charges, or excluding pending charges.
Example ledger
Consider an example where a customer is issued a $100 credit with one access segment from September 01, 2024 through October 01, 2024. During the month of September, the customer consumed $63 of the credit. The remaining credit balance expired after October 01. As a result, this credit has three ledger entries:| Type | Timestamp | Amount |
|---|---|---|
credit_segment_start | 9/1/2024 | +$100 |
credit_automated_invoice_deduction | 10/1/2024 | -$63 |
credit_segment_expiration | 10/1/2024 | -$37 |
Manual ledger entries
You may want to adjust a credit or commit’s ledger to account for mistakes, migrate existing customers with outstanding balances to Metronome, or many other reasons. Apply positive or negative adjustments to a credit or commit’s ledger through the Metronome app or API using the/addManualBalanceLedgerEntry endpoint.
Credit ledger entry types
| Type | Description |
|---|---|
credit_segment_start | Represents that a credit segment started and the customer now has access to the usage amount for that segment. The access schedule of the credit describes these segments. |
credit_automated_invoice_deduction | Represents deductions from the credit segment caused by a usage invoice that included usage applicable to this credit. |
credit_segment_expiration | Represents the unused credit amount that expired at the end of a credit segment. |
credit_manual | Represents a manual ledger entry added to a credit. |
credit_seat_based_adjustment | Represents the additional credit associated with a seat increment when using recurring credits linked to a subscription |
Commit ledger entry types
| Type | Description |
|---|---|
postpaid_initial_balance | Represents the starting balance of a postpaid commit. |
postpaid_automated_invoice_deduction | Represents deductions from the remaining obligation of the postpaid commit as the result of an invoice with usage that applies to this commit. |
postpaid_trueup | Represents a true-up invoice issued for this commit to cover usage not covered by automated usage invoices. |
postpaid_rollover | Represents unused usage from the postpaid commit which was rolled over to a new contract. |
postpaid_manual | Represents a manual ledger entry added to a postpaid commit. |
postpaid_commit_expiration | Represents commit amount unused and expired at the end of a commit segment. Does not include usage that rolled over to a new contract. |
prepaid_segment_start | Represents that a prepaid commit segment started and the customer now has access to the usage amount for that segment. The access schedule of the prepaid commit describes these segments. |
prepaid_automated_invoice_deduction | Represents deductions from the prepaid commit segment caused by a usage invoice that included usage applicable to this commit. |
prepaid_rollover | Represents unused usage from the prepaid commit that rolled over to a new contract. |
prepaid_segment_expiration | Represents commit amount unused and expired at the end of a commit segment. Does not include usage that rolled over to a new contract. |
prepaid_commit_expiration | Represents commit amount unused and expired at the end of a commit segment. Does not include usage that rolled over to a new contract. |
prepaid_manual | Represents a manual ledger entry added to a prepaid commit. |
prepaid_commit_seat_based_adjustment | Represents the additional commit associated with a seat increment when using recurring commits linked to a subscription |