This feature is currently in Beta and should not be used in a production environment.
A credit grant adds credits to a customer balance. Grants are the main way to create prepaid or promotional credit.
Every grant has an amount and a currency. A grant can also define how it’s funded, when unused credits expire, and how Metering & Billing prioritizes it against other grants during consumption.
The funding method describes how the customer receives or pays for the credits.
Use promotional credits when no payment workflow applies. Common examples include onboarding credit, compensation credit, migration credit, or admin-created credit.
Promotional credits are available without waiting for an invoice or external payment reconciliation.
Use invoice-funded credits when a customer buys credits through Metering & Billing billing.
In this flow, the grant represents the credits the customer receives, and the invoice represents the payment workflow for those credits. The credit amount and the purchase amount are related but not necessarily identical.
For example, if a customer receives 100 credits with a per-unit cost of 0.50 USD, the invoice amount is 50 USD.
credit amount: 100 credits
per-unit cost: 0.50 USD
purchase amount: 50.00 USDThis distinction is important for discounts, commitments, negotiated rates, and cases where the commercial price of a credit differs from its face value.
Use externally funded credits when invoicing and payment happen outside Metering & Billing through custom invoicing.
The grant records the credits in Metering & Billing. Your integration is responsible for updating Metering & Billing when the external payment state changes.
Priority controls which credits are consumed first when a customer has multiple grants in the same currency.
Lower priority values are consumed first. If two grants have the same priority, credits that expire earlier are consumed first. If priority and expiration are equal, Metering & Billing uses stable movement order.
Example:
|
Grant |
Priority |
Expires |
Amount |
|---|---|---|---|
| A | 1 | T10 | 100 |
| B | 1 | T20 | 100 |
| C | 2 | never | 100 |
If the customer consumes 150 credits, Metering & Billing consumes all of A, then 50 from B. C is not touched because its priority value is higher.
A grant can expire after a configured duration. Expiration applies only to unused credits. If a customer uses part of the grant before expiration, only the remaining unused amount expires.
For example, a 100 credit grant expires after 30 days. If the customer uses 40 credits before then, the remaining 60 credits expire at the expiration time.
grant: +100
consumed: -40
expired: -60Purchase terms describe how the credits are funded. They define the purchase currency and the per-unit cost used to calculate the purchase amount.
Tax configuration is relevant for revenue recognition on usage charges that consume credits. Set tax configuration on all usage charges that need to be classified correctly for revenue recognition.