Working with credits
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
- Prepaid commitments
This document describes Metronome's rich support for credits. Different credits can have varying expirations, priorities, and cost bases.
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:
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 for all usage associated with a customer, or can be tied to one or multiple specific products. When creating a product-specific credit grant, the order in which you select products or enter product_ids in your API request will determine the order in which the grant is applied to product usage.
It’s helpful to include the relevant product names in the grant name. This reduces confusion in downstream integrations (e.g., NetSuite) about which products are tied to a grant.
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. When creating product-specific credits, it’s important to configure the credit with the same pricing unit as the associated product - otherwise, the credit will not be applied to product usage. For example, if a product is priced in “Acme Cloud Credits” and a credit is applied in USD, the credit will not be accessible for this product.
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 grants have the same priority, the one that expires sooner is consumed first. If two credit grants have the same priority and expiration date, the product-specific credit is burned down first. If two credit grants have the same priority, expiration date and are both product-specific the one with the earlier effective date is burned down first.
The API exposes a create grant endpoint, which takes in the same information.
The order in which you add a plan or a grant to a customer within an invoicing period is irrelevant - you can apply a grant first, and then add a plan; or you can add a plan, and then apply a grant. Usage for that invoicing period will be applied to the grant, even if it was consumed prior to the grant being created. This does not apply outside of the invoicing period, since it is not possible to retroactively apply grants to finalized invoices.
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.
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.
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.
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.
Credits can be issued for all usage associated with a customer, or can be tied to one or multiple specific products. When creating a product-specific credit grant, the order in which you select products will determine the order in which the grant is applied to product usage.
It’s helpful to include the relevant product names in the grant name. This reduces confusion in downstream integrations (e.g., NetSuite) about which products are tied to a grant.
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.
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
Changes to customer plans will impact the customer’s product-specific grants. If you update product pricing within a plan, that will impact the rate at which a customer’s product-specific credit grant burns down. If you remove a product from a plan, archive a plan, or switch a customer to a plan without that product, the customer will no longer be charged for usage of that product, there will be no burn down of the grant, and the grant will expire at the set expiration date.
Note that a product-specific grant cannot be transferred to another product, so it will not be accessible to the customer unless they are being charged for the original product assigned when the grant was created. If you need to re-assign an existing grant to a different product, void the grant and create a new one tied to the new product.
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.
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 amount of the grant's credits has already been applied to a finalized usage invoice.
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.
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.