Skip to main content

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.

a screenshot of the Metronome app 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 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

A customer's balance of credits minus usage is tracked throughout the month, based upon valid credits at the time of usage. For example, this table walks through the calculations on a month's worth of credits and usage, with a credit grant that starts the 5th of the month and expires on the 15th.

DateValid credit grant amountUsageBalance
5th500+50 (grant)
10th5010+40 (grant)
15th000 (grant expired)
20th010-10 (pending)
31st010-20 (invoiced)

Usage that occurs while a grant is valid is subtracted by the credit grant (as a pending balance). Usage that occurs without a valid grant goes directly into the pending balance. At the end of the billing period, the finalized invoice pulls in the pending balance (along with any non-usage-based charges).

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 effective and expiry dates

Credits always apply to applicable spend that occurs when the credit grant is valid. A credit grant is considered valid if the date and time is greater than or equal to the grant's effective_at date and less than the grant's expires_at date. For example, if a customer has monthly billing periods anchored to the start of each month, and you want to create a credit grant that is valid for only the current month's billing period, you should create a credit grant that starts at 00:00 UTC on the 1st of the month, and expires at 00:00 UTC at the 1st of the next month. You can backdate grants issued within a billing period to take effect at the start of the billing period.

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 are allowed to backdate credit grants to any date after the end date of the most recently finalized billing period invoice. For example, if you create a credit grant on February 20 and the customer was last invoiced on January 31, you can backdate the grant to any date from February 1 to February 19.

You can invoice a customer for the credit grant by toggling the Invoice customer option and entering a date for issuing the invoice. The customer is invoiced for the amount paid value and receive a credit grant for the amount of credit granted value.

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.

a screenshot of the Metronome app displaying the plizard question to

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.

a screenshot of the Metronome app displaying the ability to add a grant to plan

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.

a screenshot of the Metronome app displaying the Edit Grant option

a screenshot of the Metronome app 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.

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.

a screenshot of the Metronome app displaying the Void Grant option

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.

Metronome logoMetronome logo