Manage credits

Metronome supports the ability to adjust a customer's balance by granting credits. Common scenarios for using credits include:

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

Metronome designs credits with utility in mind, allowing you to vary them by expiration, priority, and cost basis.

How credits work

Credits are created by issuing a credit grant to a customer. The flexibility of credits comes from four key qualities:

• Credits can be granted in any pricing unit, whether a currency such as U.S. dollars or a custom pricing unit like "cloud consumption units."

  When creating product-specific credits, configure the credit with the same pricing unit as the associated product. If you don't use the same pricing unit, the credit is not applied to product usage. For example, if a product is priced in “Acme Cloud Credits” and a credit is applied in USD, the credit is not available for this product.

• Credit grants have a cost basis.

  If a customer paid $8,500 to receive $10,000 credits, you can reflect this when creating the grant. Metronome calculates the 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 can have an effective date range.

  This includes both an effective_at start date and expires_at expiration date.

• Each credit grant has a custom priority.

  Priorities are positive decimal numbers, where smaller numbers represent higher priorities (that is, priority 1 has 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.

Naming a product-specific credit grant

It's helpful to include the relevant product names in the credit grant name. This reduces confusion in downstream integrations about which products are tied to a credit grant.

Append-only ledgers

Credits are tracked in Metronome through 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 Metronome app 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 credit 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 Metronome app displays credit grants and ledgers up to the end of the customer's current billing period. You can use the /credits/listEntries and /credits/listGrants endpoints to view the full details of credit grants and consumption, including future credit 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 are 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 are consumed. The remaining 200 CCUs owed are 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.

When to add a credit grant

When you add a plan or a credit grant to a customer within an invoicing period is irrelevant. You can apply a credit grant first and then add a plan, or you can add a plan and then apply a credit grant. Usage for that invoicing period applies to the credit grant, even if it was consumed prior to the credit grant being created. This does not apply outside of the invoicing period, since it is not possible to retroactively apply credit grants to finalized invoices.

Credit grant expiry dates

Because credits are consumed at the time of invoicing, the expiry date of a credit grant should generally align with a customer's billing periods. For example, if a customer has monthly billing periods anchored to the start of each month, they 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 cannot apply to a February invoice.

Revenue recognition

Accrual-based revenue recognition requires that you recognize revenue at the time of service delivery, not at the time payment was collected. Credit grants make proper revenue recognition straightforward.

Using the ledger view in the Metronome app or the /credits/listEntries endpoint, you can see which credits were consumed in a given time period and the exact cost basis for each entry. In the previous 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.

Grant credits to customers

Grant credits to a customer through the Metronome app or the API.

When creating a product-specific credit grant, the order you select products in the Metronome app or enter product_ids in your API request determines the order the credit grant is applied to product usage.

To grant credits through the Metronome app, go to Customers > select the customer > Credits > click Issue grant.

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

You may issue credits for all usage associated with a customer, or can be tied to one or multiple specific products.

You can invoice a customer for the credit grant by toggling the Invoice customer option and entering a date for issuing the invoice.

The API exposes a /createGrant endpoint, which accepts the same parameters as the Metronome app.

Grant credits automatically

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

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

To grant credits automatically with a plan, associate a credit grant with the plan in the plan creation wizard.

After you've selected products to add to the plan and set their pricing, you 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 credit grant becomes effective on the start date of when a customer is assigned to a plan. The following credit grants 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 determines the order in which the credit grant is applied to product usage.

Model 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 credit grant to invoice the customer. Setting a credit grant to invoice a customer generates a separate invoice which is billed in-advance at the beginning of each billing period for the customer cost you designate in the credit grant.

A customer may buy a block of credits, which are burned down with usage. Any credits remaining at the end of the commitment period expire. Many Metronome clients prefer this approach, given the simplicity (no fixed fees, no fee pro-ration)—which can result in a better customer experience and easier revenue recognition.

Model free trial credits

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

Change a credit grant

You can modify a credit grant's name, reason, or expiry date using the Metronome app. To do so, click on the customer's Credits tab and then click on Grants. Find the applicable credit 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.

Grant modification limitations

You cannot modify credit grants that have been voided or that expired before the end date of the customer's most recently finalized usage invoice.

Burning down product-specific credit grants

Changes to customer plans impact the customer's product-specific credit grants. If you update product pricing within a plan, that impacts 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 is no longer charged for usage of that product, there is no burn down of the credit grant, and the credit grant expires at the set expiration date.

Note that a product-specific credit grant cannot be transferred to another product, so it cannot be accessible to the customer unless they are being charged for the original product assigned when the credit grant was created. If you need to re-assign an existing credit grant to a different product, void the credit grant and create a new one tied to the new product.

Void a credit grant

You can void a credit grant using the Metronome app. To do so, click on the customer's Credits tab and then click on Grants. Find the applicable credit 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 credit grants appear at the bottom of the credit grant list in the Metronome app and are not included in the /listGrants nor the listEntries responses.

Cannot void partially consumed credit grants

You cannot void a credit grant if any amount of the grant's credits has already been applied to a finalized usage invoice.