Skip to main content
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. There are many ways to display remaining balance to customers and Metronome provides the flexibility to display both aggregated and detailed views.
Balance values can be fractional numbers (e.g., 0.8 cents for USD). When integrating with the balances API, do not truncate balances to integers — doing so may cause data loss. Rounding is acceptable if done intentionally. For USD, amounts are denominated in cents, so a balance of 0.8 represents $0.008.

​
Fetch the total remaining balance on a customer

To display an aggregated real-time balance to your customers, call the /getNetBalance endpoint. This endpoint returns a single aggregated sum of the remaining balance on a customer, with advanced filtering by balance type, currency, pending charges, and custom fields.

​
Build a detailed ledger view of individual balances

Metronome also supports more detailed views of individual balances by tracking ledger entries using the listBalances endpoint. 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 total 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:
TypeTimestampAmount
credit_segment_start9/1/2024+$100
credit_automated_invoice_deduction10/1/2024-$63
credit_segment_expiration10/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

TypeDescription
credit_segment_startRepresents 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_deductionRepresents deductions from the credit segment caused by a usage invoice that included usage applicable to this credit.
credit_segment_expirationRepresents the unused credit amount that expired at the end of a credit segment.
credit_manualRepresents a manual ledger entry added to a credit.
credit_seat_based_adjustmentRepresents the additional credit associated with a seat increment when using recurring credits linked to a subscription

​
Commit ledger entry types

TypeDescription
postpaid_initial_balanceRepresents the starting balance of a postpaid commit.
postpaid_automated_invoice_deductionRepresents deductions from the remaining obligation of the postpaid commit as the result of an invoice with usage that applies to this commit.
postpaid_trueupRepresents a true-up invoice issued for this commit to cover usage not covered by automated usage invoices.
postpaid_rolloverRepresents unused usage from the postpaid commit which was rolled over to a new contract.
postpaid_manualRepresents a manual ledger entry added to a postpaid commit.
postpaid_commit_expirationRepresents 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_startRepresents 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_deductionRepresents deductions from the prepaid commit segment caused by a usage invoice that included usage applicable to this commit.
prepaid_rolloverRepresents unused usage from the prepaid commit that rolled over to a new contract.
prepaid_segment_expirationRepresents 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_expirationRepresents commit amount unused and expired at the end of a commit segment. Does not include usage that rolled over to a new contract.
prepaid_manualRepresents a manual ledger entry added to a prepaid commit.
prepaid_commit_seat_based_adjustmentRepresents the additional commit associated with a seat increment when using recurring commits linked to a subscription