Prepaid credits

Prepaid credit lets a customer pay for usage before they use it. They buy credit, or you give it to them, and the usage that the credit covers costs them nothing more on the invoice. Each lot of credit is a credit grant: an amount for one customer, in money or in your own credit unit, with an expiry date if you set one.

Credit pays the usage lines of a subscription's invoices. It does not pay the plan fee, one-time charges or an invoice that you create by hand.

Name your own credit unit

Skip this to sell credit in money ("USD 10.00 of credit"). A credit unit lets you sell "1,000 credits" instead.

The first grant in a unit locks its currency, value and decimal places. After that, you can change only the names. Archive a unit to stop new grants in it. Customers keep the credit they have and can still use it.

Give credit by hand

Open the customer, select View credits on the Credits card, then Give credit.

Paid credit always has an invoice. Select Create invoice, and the credit starts when the invoice is paid. If you already have the money, select Mark the invoice as paid and enter the Payment method, a Reference and the date in Paid on: the invoice is paid and the credit is active in the same step. Either way, the drawer ends with a link to the invoice.

To give paid credit, your role needs permission to manage invoices as well as credits.

Sell credit packs

A credit pack is a one-time price that gives paid credit when its invoice is paid.

The price can be less than the credit it gives. A pack that sells 1,000 credits worth USD 10.00 for USD 9.00 has a cost basis of USD 9.00. A pack invoice never uses credit itself, so free credit cannot buy paid credit.

Purchase limits in Settings → Credits set the minimum and maximum value of the packs on one purchase, per currency, through checkout, payment links, the portal and manual invoices. Credit that you give by hand has no limit.

Include credits in a plan

On a recurring price of a plan, turn on Give credit each billing period in the Grants credit card. Set the amount each period (multiplied by the quantity on the subscription) and the Priority. Plan credit is promotional: it is part of the plan fee, so it has no cost basis.

The first period's credit arrives when the first period is billed. A trial gives no credit: the credit starts with the first paid period. Each period's credit ends with that period.

Under At the end of the billing period, select what happens to credit that is not used:

Carried credit does not move a second time. It lasts until its own expiry.

For example, a plan gives 1,000 credits each month, carries 50% with a maximum of 150, for one period. The customer uses 600. Of the 400 left, 50% is 200, and the maximum makes it 150. The next month starts with 1,000 new credits and 150 carried credits that expire at the end of that month.

Renew credits on their own clock

Plan credit can renew more often than the bill. A plan billed yearly can still give 25 credits each month. Under Renews, select how often:

Credits do not renew every hour. Use an allowance on an entitlement for an hourly limit.

Under Windows start, select where each window begins:

• From the subscription start: windows start at the start of the billing term. The last window of a term ends at the term end.
• On the calendar: on the hour, at midnight, on Monday, or on the 1st of the month, quarter, half year or year, in the business time zone. A first window that starts before the subscription gets the full amount, unless your billing settings say otherwise.

Each window's credit pays only the usage inside that window, also on a yearly invoice. Daily credit for 2 May does not pay usage from 3 May. The invoice line stays one line.

Carry unused credit works for each window: the part moves to the next window, and A number of renewals counts windows. The customer portal and the access check show when the credit renews next (renews_at).

Your billing settings decide what happens to window credit when the plan changes, when the subscription pauses, and when it is set to cancel at the end of the term:

When your billing settings move the windows on by the paused time, the window that is open at the pause runs on for the paused time: its credit expires that much later. From the subscription start, every later window moves too. On the calendar, only the next window moves: it starts when the extended window ends and stops at the next calendar boundary, so it is shorter. The short window follows the same rule as a partial first window: the full amount, an amount prorated for its part of the calendar window (rounded to the nearest whole step of the unit), or nothing until the next full window. After it, the windows are on the calendar again. A pause that ends past a calendar boundary skips that boundary. A resume that starts a new term starts the windows again from that term.

An allowance on an entitlement can renew with these credits: see Renew an allowance.

With the API, set reset on the price's grants_credit:

{
  "kind": "per_cycle",
  "unit": "credit",
  "amount": 25,
  "reset": { "every": "month", "count": 1, "anchor": "subscription" }
}

How credit applies to an invoice

When an invoice is finalized, grants pay its usage lines in this order:

1. Restored credit (credit given back from an earlier invoice).
2. The lowest Priority.
3. The soonest expiry. Credit with no expiry goes last.
4. Promotional before paid.
5. The oldest grant.

Usage that no grant covers bills as usual. Credit with an expiry date still pays for usage from before that date, on the invoice that bills it.

Credit and tax

Promotional credit and credit that is Taxed at purchase apply before tax: they lower the amount that tax is charged on. For paid credit taxed at purchase, the tax was already on the pack invoice.

Credit that is Taxed at use applies after tax. Its pack invoice has no tax. On the usage invoice, the credit pays the rest of the usage and the tax on it, as money. We never gross up the tax.

Example, with 20% tax. A customer has USD 20.00 of promotional credit and a USD 100.00 pack taxed at use. They use USD 50.00:

The pack has USD 64.00 left. The promotional credit paid no tax, so the tax is USD 6.00, not USD 10.00.

Set the default for paid credit in Settings → Credits → Default tax treatment for paid credit. With Not set, each paid credit pack must set its own.

Stop usage when credit runs out

By default, usage never stops for lack of credit: what credit does not cover goes on the invoice. To stop it, open Settings → Credits and turn on Block usage when credit is used up.

Blocking acts on the access check: the call your app makes before each request. When the customer has no credit available, the check answers that the request is not allowed, and your app does not make the request. Usage that your app already sent is always billed.

With blocking on, the first of these sets the policy for a customer:

1. The customer's override, until the date it ends.
2. The policy on a credit grant (When this credit is used up).
3. The policy on the plan price.
4. The Default policy in Settings → Credits: Bill usage (the default) or Block usage.

The Overdraft limit lets the balance go below zero before we block, per currency. 0 blocks at zero.

Set an override for one customer

On the customer's Credits page, select Edit on Settings for this customer. Select Block usage or Bill usage, and a date in Override ends on if the override is for a time only, such as a trial of a higher volume. You can also set an Overdraft limit for this customer, for example a trusted customer who can go USD 2.00 below zero. Leave it empty to use the business limit. These controls show only while blocking is on.

The Available credit card shows the policy that applies now and what sets it.

Holds

When many requests run at the same time, your app can place a hold before each one. The hold reserves the estimated cost, so two requests cannot spend the same credit. When the request ends, your app captures the hold with the real usage, or releases it.

The customer's Credits page lists Open holds with their amount, meter and expiry. An open hold counts against the balance. To free one by hand, select Release hold. The app cannot capture it after that. Releasing needs permission to hold, capture and release credit.

In Settings → Credits:

The open holds limit and the "no credit" refusal apply only when the policy is Block usage. With Bill usage, a hold only records the reservation.

Take credit back, or give it back

Void a promotional grant. On the customer's Credits page, select Void grant on the grant. The customer loses what is left. You cannot undo this.

Refund a paid grant. Paid credit leaves only through a credit note on the invoice that sold it. A credit note on a pack line removes the unused part of the credit in proportion, up to the part not used yet.

Void an invoice that credit paid. The credit goes back to the grant it came from. If that grant has expired, the credit goes to a new grant of the same kind, which is used first and expires 12 months later.

Refund or credit an invoice that credit paid. The credit's share comes back as credit, never as cash. The credit note shows it as Credit Grants Returned.

See the balance and every movement

The customer's Credits page has:

• Available credit: the credit left, less unbilled usage that credit pays and open holds, plus any overdraft limit. The invoice shows the final amounts.
• Credit grants: each grant with its category, what remains, its cost basis, its expiry and its source (Purchase, Plan credits, Given by hand, Restored).
• Transactions: each movement, newest first: Granted, Activated, Applied to invoice, Expired, Voided, Restored, Rolled over in and Rolled over out. Filter by grant, movement, category, unit, invoice and date.

In the customer portal, the Credits section shows the customer their credit, each grant with its expiry, the Buy credits list and their Credit history.

Related

• Spend limits, alerts and automatic top-up
• Meters and rate cards
• Bill from the AI model price list
• Usage pricing
• Prepaid AI credits and holds with the API