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 customer 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.

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.

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 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.