> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metronome.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Optimize performance with commits and credits

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.

```bash theme={null}
curl --request POST \
  --url https://api.metronome.com/v2/contracts/commits/moveToHistory \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
    "contract_id": "771f108d-2457-47ad-8bee-7c87de04ac36",
    "commit_ids": ["4ad19ea9-6df5-4c72-a487-92480b4faf5b"],
    "dry_run": false
  }'
```

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