Skip to main content
Metronome provides a performance optimization where users can move prepaid commits or credits that are expired or fully exhausted to history. By using this functionality, you can optimize performance and support tens of thousands of commits and credits over time on a customer.

Move commits or credits to history

Users can move a prepaid commit or credit to history if the following is true:
  • The prepaid commit or credit is at the contract level. Customer-level commits and credits are not yet supported.
  • The prepaid commit or credit is fully depleted (remaining balance is $0 based on finalized usage statements), or its access period has ended.
  • The prepaid commit or credit is not the source for a rollover commit/credit.
  • Payment invoices for the commit are finalized.
  • The commit is the only item charged on the payment invoice.
Historical commits are not shown in default UI views or in balance endpoints. Instead, Metronome provides dedicated API endpoints and UI experiences to allow viewing historical commits and credits. Payment invoices associated with historical commits (e.g. auto top-up purchases or purchases for manual payment-gated commits) are also moved to cold storage. These scheduled invoices will not appear by default on the Invoices tab in the UI, or on the listInvoices API. Users can pass an optional parameter on the listInvoices API to view these scheduled invoices.

Manually moving credits and commits to history

Use the /moveToHistory endpoint to move specific prepaid commits and credits to history. You can use the dry-run functionality to preview which prepaid commits or credits meet the eligibility criteria.

Automatically move credits and commits to history

By navigating to the Developer > Optimization tab, you can configure an automated job to move eligible prepaid commits and credits to history after a selected number of months have passed. If you use this functionality, you do not need to manually call the /moveToHistory endpoint. Enabling this automated job requires specific permissions - reach out to Metronome if you don’t see this option.

Interacting with credits and commits that are moved to history

Viewing historical commits and credits

Use the listHistoricalBalances endpoint to fetch credits and commits that were moved to history, including information about their access and invoice schedules, ledger, and when they were moved to history. You can also view details about historical commits and credits in the UI.

Viewing payment invoices for historical commits

By default, the listInvoices endpoint will not return payment invoices for historical commits. Pass the parameter include_historical_commit_invoices: true to retrieve these invoices. Calling the getInvoice endpoint with the id of a payment invoice for a historical commit will continue to return that invoice. Similarly, navigating to the Invoices tab for a customer will not show payment invoices for historical commits. To view these invoices, first navigate to a historical commit, then click on its invoice schedule to view its payment invoice.

Data Export

Commits and credits that are moved to history continue to be exported in the balances table, with a column moved_to_history_at denoting when they were moved to history.

Voiding and regeneration

To void and regenerate a usage invoice with a historical credit or commit applied, the commit must be moved out of history. On voiding a usage invoice, Metronome automatically moves any credits or commits that were applied to the usage invoice out of history. On regenerating the usage invoice, Metronome automatically moves any historical credits or commits with an access schedule overlapping the usage invoice’s service period out of history as well. After the regeneration completes, commits will not be moved back to history automatically. Use the moveToHistory API, or if configured wait for the automated job to pick them up.