Skip to main content

Working with credits

The move to credit grants

Metronome has historically supported credits with a simpler single-ledger model. If you're still using legacy credits, the Metronome team will reach out and work with you on migrating to credit grants. Credit grants offer improved flexibility and easier revenue recognition.

Credits allow customers to hold a balance entitling them to some usage of your product. Common scenarios for using credits include the following:

  • Prepayment, typically at a discounted rate
  • Reimbursement for downtime
  • Promotions

This document describes Metronome's rich support for credits. Different credits can have varying expirations, priorities, and cost bases.

Terminology: credits and pricing units

The term "credits" can sometimes be overloaded in the context of pricing and billing. Many companies price in something they call credits, e.g. "Acme Cloud Credits." In Metronome, this is called a custom pricing unit. U.S. dollars and Acme Cloud Credits are both examples of pricing units.

In Metronome, the word "credits" always refers to a customer's consumable balance of some pricing unit. For example, a customer may have $500 in credits available to them, or they might have a credit balance of 5,000 Acme Cloud Credits.

Granting credits to customers

To grant credits to a customer, you can either use the web UI or the API. In the web UI, an Issue grant button can be found on a customer's Credits tab. Clicking this brings up the following pane:

a screenshot of the Metronome UI showing the creation of new credit grant

The credit grant name will appear on the customer's invoice, but the optional reason will not. This is only visible in the Metronome UI and is useful for tracking things like support ticket numbers or incident IDs.

Credits can be issued in any pricing unit, whether a currency such as U.S. dollars or a custom pricing unit like "cloud consumption units." In the preceding example, the credit grant is for U.S. dollars.

Credit grants also keep track of a cost basis for the credits. In the preceding example, the customer paid $8,500 to receive $10,000 credits, which works out to a cost basis of $0.85 per $1 credit. This number doesn't appear on customer invoices, but it's important for your internal accounting. (See the Revenue recognition section below for more details.)

You can invoice a customer for the credit grant by toggling the Invoice customer option and entering a date for issuing the invoice. This date cannot be before today's date.

Each credit grant has an effective date range and a custom priority. Priorities are positive decimal numbers, where smaller numbers represent higher priorities (i.e. priority 1 is higher priority than priority 2). If a customer has multiple credit grants that could be applied to an invoice, Metronome always chooses the one with the higher priority. If two credit grant have the same priority, the one that expires sooner is consumed first.

The API exposes a create grant endpoint, which takes in the same information.

Append-only ledgers

Credits are tracked in Metronome via append-only ledgers. Each of a customer's credit grants has a ledger, and those ledgers combine to form one cumulative ledger per pricing unit. Entries in this ledger record the details of each change, as well as what user made the change and when. Because entries can only be added to the ledger, you always have a full audit trail of all changes that have been made.

You can view a customer's credit ledgers in the web UI by clicking on that customer's Credits tab. Two views are available: Ledger and Grants. The former represents all credit changes for a given pricing unit as a single ledger, while the latter shows the details of individual grants.

a screenshot of the Metronome UI displaying a customer's USD credit ledger

The ledger can include pending entries, such as deductions from invoices that are still in the draft state. The Available balance at the top of the ledger takes these pending entries into account when calculating the remaining credit balance.

The credits UI displays grants and ledgers up to the end of the customer's current billing period. You can use the list credit ledger entries and list credit grants API endpoints to view the full details of credit grants and consumption, including future grants.

Granting credits automatically

You can automatically grant credits to any customer who is assigned to a plan. This includes:

  • Granting free trial credits for any customer who signs up for a specific plan
  • Modeling a recurring, prepaid, credit-based business model

To grant credits automatically with a plan, indicate that you would like to associate a grant with the plan in the plan creation wizard.

a screenshot of the Metronome UI displaying the plizard question to

After you’ve selected products to add to the plan and set their pricing, you will see a new view in the plan creation wizard in which you can add a credit grant and an associated schedule.

a screenshot of the Metronome UI displaying the plizard add grant to plan

You are able to set the name, pricing unit, customer cost, priority, and schedule for the credit grant. The first grant will become effective on the start date of when a customer is assigned to a plan. The following grants will become effective on the start date of the billing period as defined by the recurrence schedule.

Modeling prepaid credit plans

In a prepaid credit business model, customers purchase a number of credits at the beginning of the billing period and then draw down from those credits over time. To model a prepaid credit-based plan, set the number of credits you want customers to buy in advance, designate the corresponding amount you want to charge the customer for those credits, and set the grant to invoice the customer. Setting a credit grant to invoice a customer will generate a separate invoice which is billed in-advance at the beginning of each billing period for the customer cost you designate in the grant.

Modeling free trial credits

To model trial credits, you can set it to be a one-time grant and the customer cost in this case will be $0.00.

Making changes to a grant

You can modify a grant's name, reason, or expiry date using the web UI. To do so, click on the customer's Credits tab and then click on Grants. Find the applicable grant, click on the three dots in the upper right corner, and select Edit grant.

a screenshot of the Metronome UI displaying the Edit Grant option

a screenshot of the Metronome UI displaying the Edit Grant pane

When editing the expiry date, the new date must not be before the end date of the customer's most recently finalized usage invoice.


You cannot modify a grant if any of the following scenarios apply:

  • the grant has been voided
  • the grant expired before the end date of the customer's most recently finalized usage invoice

Voiding grants

You can void a grant using the web UI. To do so, click on the customer's Credits tab and then click on Grants. Find the applicable grant, click on the three dots in the upper right corner, and select Void grant. Confirm your selection by clicking the red Void Credit Grant button.

a screenshot of the Metronome UI displaying the Void Grant option

Voided grants will appear at the bottom of the grant list in the web UI and are not included in the list credit grants nor the list credit ledger entries API responses.


You cannot void a grant if any of the following scenarios apply:

  • any amount of the grant's credits has already been applied to a finalize usage invoice
  • an invoice has already been issued to the customer for the purchase of the grant

Credits and invoicing

Credits are automatically deducted from a customer's balance at the time of invoicing. At the end of a billing period, all of a customer's credits that have not yet expired are eligible to be used. If an invoice includes a custom pricing unit, credits in that pricing unit will be used first before any overage is converted to the invoice's currency.

For example, suppose a customer has 800 credits remaining in a pricing unit called Cloud Consumption Units (CCUs). In the current billing period, they have accrued charges in the amount of 1,000 CCUs. When their invoice is produced, the 800 CCU credits will be consumed. The remaining 200 CCUs owed will be converted to U.S. dollars using the plan's overage price. If the customer also has U.S. dollar credits available, those could then be used to pay the USD total due.

Consumed credits appear on an invoice as negative adjustments and an automatic deduction is made to the appropriate credit ledger with the user "Metronome System" as the creator of the ledger entry.

Credit grant expiry dates

Because credits are consumed at the time of invoicing, the expiry date of a credit grant should generally line up with a customer's billing periods. For example, if a customer has monthly billing periods aligned to the start of each month, they will receive one invoice for the month of January, one for the month of February, etc. If they have a credit grant that expires on February 20th, those credits can apply to a January invoice but won't apply at all to a February invoice.

Credit expiry dates are exclusive, so a credit grant that expires on February 1st can be used for a January invoice, but one that expires on January 31st cannot. For this example customer, a credit grant that expires on February 1st is effectively the same as one that expires on February 20th. To avoid confusion, we recommend aligning credit grant expiry to billing period dates.

Revenue recognition

Accrual-based revenue recognition requires that you recognize revenue at the time of service delivery, not at the time payment was collected. In the example credit grant at the beginning of this document, $8,500 was collected up front from the customer, but it must be gradually recognized as revenue only as the credits are consumed.

Credit grants make proper revenue recognition straightforward. Using the ledger view in the web UI or the list credit ledger entries API endpoint, you can see which credits were consumed in a given time period and the exact cost basis for each entry. In the earlier ledger screenshot, you can see that $100 in credits was consumed in the month of January, with a cost basis of $0.85 per credit. This means $85 in revenue should be recognized.