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.
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 thelistHistoricalBalances 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, thelistInvoices 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 thebalances 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 themoveToHistory API, or if configured wait for the automated job to pick them up.