Billing creditsVersion bêta publique

Use credit grants to offer billing credits to your customers in your business workflows, such as the following:

• Prepayment: Grant billing credits to your customers that they can use to pay for usage-based products or services, such as memberships, pay-as-you-go plans, subscriptions, or specific products or services.
• Promotional offering: Grant billing credits for free to your customers as a promotional offering. Businesses often offer a limited amount of promotional credits, and typically with an expiration date.

The following diagram shows how billing credits work with usage-based billing:

Use cases for billing credits

Refer to the following guidance for using billing credits.

Approved uses

• You can issue billing credits to your customers either for free or for a fee.
• Your customers can use billing credits to pay for memberships, pay-as-you-go plans, subscriptions, or specific products or services that you offer.

Prohibited uses

• You can’t issue billing credits as gift cards or gift certificates. Also, you can’t allow your customers to spend billing credits on, or exchange billing credits for, gift cards or gift certificates.
• You can’t offer billing credits as stored value to your customers. That means you can’t grant any billing credits that aren’t intended for spending on memberships, pay-as-you-go plans, subscriptions, or specific products or services that you offer.
• You can’t allow your customers to use billing credits for payments to third parties. For example, you can’t allow them to apply billing credits to purchases on the website or platform of another business.
• You can’t link billing credits to digital wallets, or allow your customers to do so. For example, you can’t allow your customers to add billing credits to a digital wallet, such as Apple Pay or Google Pay.

Credit grants

A credit grant tracks a set of prepaid or promotional billing credits allocated to a customer. Credit grants have the following states:

Credit grant eligibility

You can apply credit grants to invoices if all of the following are true:

• The invoice’s period_end is on or after the credit grant’s effective_at time.
• The invoice’s period_end occurs before the credit grant’s expires_at time, if set.
• The credit grant has an available balance when the invoice finalizes.
• The credit grant’s currency matches the invoice currency.

You can’t apply credit grants to:

• Non-subscription invoices, such as one-off invoices
• 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

Apply credit grants

You can apply credit grants to subscription invoice line items that link to a billing meter price. Credit grants apply to invoices after discounts, but before taxes and the invoice credit balance.

Multiple invoices or line items

If you can apply a credit grant to multiple invoices, the credit applies first to the invoice that finalizes first. Because subscription invoices finalize independently as soon as they’re eligible, we can’t guarantee the finalization order.

If you can apply a credit grant to multiple line items on the same invoice, the credit applies to the line items in the order they appear on the invoice.

Multiple credit grants

If you can apply multiple credit grants to an invoice or line item, they’re prioritized as follows:

1. Expiration date: Credit grants with earlier expires_at timestamps apply first.
2. Category: Credit grants with the promotional category apply first.
3. Effective date: Credit grants with earlier effective_at timestamps apply first.
4. Created date: Credit grants with earlier created timestamps apply first.

Upcoming, draft, or finalized invoices

Credits apply to invoices only at the time of finalization. If you apply credits to an upcoming or draft invoice, those credits might change if a finalized invoice uses them first.

Example 1: At the end of a cycle, the same set of credits appear on both a draft invoice and an upcoming invoice. When finalized, the draft invoice uses the credits. The upcoming invoice adjusts to accurately reflect any remaining credits from the credit grant.

Example 2: A customer has multiple active subscriptions and the same set of credits appear on an upcoming invoice for all of the subscriptions. If there aren’t enough credits to apply to all the subscriptions when the invoices finalize, only some invoices receive the credits. If you use billing thresholds, they might trigger later than expected because of the credits that apply to multiple upcoming invoices.

Credit balance summaries and transactions

The credit balance summary shows the following for a customer:

• Ledger balance: The balance amount reflects the billing credit balance after recording all relevant account ledger transactions. A credit grant is backed by an immutable, append-only ledger.
• Available balance: The billing credit balance available for the customer to use. This amount is equal to the ledger balance less any expired credits or unrecorded transactions.

Credit balance transactions are the credits and debits that impact a credit grant. For example, you might see a credit transaction for initial funding of the credit grant, or a debit transaction for a credit grant on an invoice.

Void invoices and issue credit notes

The following is true if you void invoices and issue credit notes:

• Voiding an invoice with credits applied reinstates the applied balance to the credit grant. If the credit grant is past the expiration date, the reinstated credits expire immediately.

• Issuing credit notes doesn’t refund credit grants applied to an invoice. To restore those billing credits, you must create a new credit grant.