Credits

Introduction

Credits are prepaid balance that customers spend toward usage and invoices instead of being charged on every action. A customer's account balance is the sum of their active credit grants.

Common patterns:

• Prepaid balance — Customers top up; usage or invoices draw down the balance.
• Promotional credits — Sign-up bonuses, goodwill, or marketing credit used before charging the payment method.
• Hybrid billing — Combine subscriptions or fixed fees with usage; bill-on-event metered usage can settle from credits instead of invoicing immediately.

Credit grants

A credit grant is a spendable bucket on a customer account. Each grant records the amount issued, the amount available, lifecycle state (pending, granted, depleted, expired, or voided), priority for consumption order, and effective and expiry windows. Grants can also be restricted to specific products so they only apply to usage charges for those products.

Credit grant payment types:

• Promotional — Free credits; no payment required from the customer.
• Paid — Customer pays for the credits, and the grant captures the payment details for reconciliation.

And a credit type:

• Currency — Balance in real money, spendable on invoices and on usage-based charges from subscriptions.
• Credit asset — Balance in a custom credit asset you define (for example tokens or coins).

Credit assets

By default, a credit grant holds a currency balance, so it can be spent against invoices and usage-based charges on subscriptions like any other money on the account.

Credit assets let you define non-currency credit types that fit your product — tokens, coins, API credits, storage units, view minutes, and so on. A grant can hold balance against one of these custom assets instead of a currency.

Examples by business type:

• Gaming / apps — Coins or gems users buy or earn and spend on items or features.
• API / developer platforms — Tokens or API credits consumed per request.
• Marketplaces — Seller credits or platform balance applied to fees or withdrawals.
• Content / media — View credits, download credits, or streaming minutes.

Credit asset balances are not yet tied to products, so they cannot be auto-consumed by subscription usage or invoices. For now you debit them yourself as customers use your product, using debit account balance and read remaining balance with get account balances.

Issuing a credit grant

You issue a credit grant against a customer account with an amount, an optional expiry, and either a currency or a credit asset. Paid grants additionally capture the payment so you can tie issued credit to a transaction. See create credit grant.

Credit consumption

When more than one grant is eligible for the same spend, consumption is deterministic. Grants are consumed in this order:

1. Earliest expiring grants first, so balance is used before it lapses.
2. Then by priority (lower priority value is consumed first).
3. Then by creation time, oldest first.

A grant can optionally be restricted to specific products. Restricted grants only apply to usage charges for those products; unrestricted grants apply to any eligible spend on the account (still subject to currency or asset match, availability, and expiry). When a charge is settled without a product context, only unrestricted grants are considered.

Credit expiry

Expired grants are excluded from available balances. Any subsequent spend draws from the next eligible grant.