Billing creditsPublic preview
Use billing credits to bill for prepaid or promotional usage-based products or services.
Use credit grants to offer credits to your customers in your business workflows, such as the following:
- Prepayment: Grant billing credits at the exchange of prepayment from your customer for usage-based products or services.
- Prepaid models can bring immediate cash flow, establish more predictable revenue, and support liquidity and financial steadiness.
- Promotional offering: Grant billing credits for free to users as a promotional offering. Businesses often offer a limited amount of promotional credits (typically with an expiration date).
How billing credits work
Credit Grant | A credit grant tracks a set of pre-paid (or promotional) credits for a given customer. |
Credit Balance Transactions | Credit balance transactions are an auditable history of changes and actions that impact a particular credit grant. These transactions can either be credits or debits. Some examples:
|
Credit Balance Summary | The credit balance summary shows a customer’s current ledger and available balance.
|
This diagram demonstrates how billing credits work with usage-based billing concepts:
Credit lifecycle
A credit grant can be in one of several states, including pending grant (before effective_at), granted and available for use, depleted (balance fully used), expired (on or after expires_at), and voided.
Grant
Each credit grant has an effective_at timestamp that indicates when they’re eligible to use. If you don’t explicitly specify this field, the credit grant defaults to being effective immediately. You can also set effective_
to a future timestamp. In this case, the credit grant has a zero available balance until the specified effective time. At the effective time, the credits are granted and the available balance adjusts accordingly. You can’t specify a past time for effective_
, and you can’t update the field on an existing credit grant.
Expiration
Optionally, you can specify a future expires_at field for a credit grant. At the expiration time, the available balance for the credit grant becomes zero. If you don’t set this field, the credits won’t expire. Additionally, you can immediately expire any remaining credits for a credit grant through the Dashboard or using the API.
Void
You can void any credit grants that haven’t been applied to an invoice. Voided credit grants won’t apply to future invoices. You can’t void a credit grant that has been applied to an invoice, either partially or completely. However, you can still expire any remaining credits.
Credit application on invoices
When integrating with billing credits, you must consider the eligibility criteria and nuances associated with credit applications on different types of invoices.
Credit grant eligibility
Credit grants can apply to subscription invoice line items that link to a billing meter price. Credit grants don’t apply to
- Non-subscription invoices (for example, a one-off invoice)
- Line items on subscription invoices that link to licensed prices
- Line items on subscription invoices that link to prices using the legacy usage records API
We use the invoice period_end, which is when the invoice generates, to decide if a credit grant is eligible to apply to the invoice. The credit grant is eligible to apply to the invoice if all of the following are true -
- The invoice
period_
is on or after the credit grant effective_at time.end - The credit grant doesn’t have an expires_at set. If it does, the invoice
period_
is before the credit grantend expires_
time.at - The credit grant has a positive available balance at the time the invoice is finalized.
- The currency of the credit grant matches the invoice currency. You can only issue credit grants in the customer’s default currency.
The invoice uses applicable credits from an eligible credit grant. Credit grants apply to invoices after discounts, but before taxes and the invoice credit balance.
Credit grants application on multiple invoices and line items
If a credit grant is eligible to apply to multiple invoices, the invoice that finalizes first consumes the credits first. There are no strict guarantees about the finalization order of subscription invoices–they finalize independently as soon as they’re eligible. Similarly, if a credit grant is eligible to apply to multiple line items on the same invoice, there’s no guarantee about the ordering in which the line items consume credits. The line items typically consume credits one by one in the order they appear on the invoice.
Credits on upcoming, draft, and finalized invoices
Credits get consumed by invoices only at the time of finalization. The credit applications you see on upcoming invoices and draft invoices can change over time. For example, a finalized invoice might use the credits that you see on an upcoming invoice a few minutes later.
At the end of a cycle, the same set of credits might appear on both a draft invoice and the upcoming invoice for the next cycle, assuming the effective and expiration times make the credits eligible for both. When finalized, the draft invoice uses the credits. The upcoming invoice then adjusts to accurately reflect any remaining credits from the credit grant.
If a customer has multiple active subscriptions, the same set of credits might appear on the upcoming invoices for all of them. If the credits are insufficient to cover all the subscriptions when finalized invoices are generated, then only some invoices might use the credits. If you also use billing thresholds, the thresholds might trigger later than expected due to credits that apply to multiple upcoming subscription invoices.
Credit grant prioritization
If you have multiple credit grants eligible to apply to an invoice line item, they’re prioritized as follows:
- Expiration date: credit grants with earlier expires_at timestamps are used first.
- Category: credit grants with category
promotional
are used first. - Effective date: credit grants with earlier effective_at timestamps are used first.
- Created date: credit grants with earlier created timestamps are used first.
Voiding invoice and issuing credit notes
The following limitations apply to voiding invoices and issuing credit notes:
- Voiding an invoice that has credits applied doesn’t reinstate the applied balance to the credit grant.
- Issuing credit notes doesn’t refund credit grants applied to an invoice. To restore those billing credits, create a new credit grant.
Use cases for billing credits
Approved uses
- Selling specific products or services
- Offering memberships for product/service suites
Restricted uses
Don’t use for:
- Selling gift cards
- Offering stored value to your customers
- Offering a wallet functionality
- Enabling the purchase of products or services from third parties
Your responsibilities
- Comply with legal and regulatory obligations (for example, KYC)
- Obtain customer consent for transaction terms
- Follow card network rules (for example, Visa)
For more information on Stripe’s policies and best practices, see the website checklist. We recommend consulting with legal counsel before using this feature to ensure compliance with all applicable regulation