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

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.

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.