How credit balances work

Overview

Credits let you bill from a prepaid balance instead of charging only after usage happens. You can sell credits directly, include them in a plan, or grant them manually as a top-up or promotion.

In Paid, a customer’s available credits are made up of one or more credit allocations. Each allocation has its own amount, timing, and optional expiry rules. Paid keeps the running balance for you and deducts credits automatically as usage is recorded.

This page explains how customers receive credits, how Paid decides which credits to spend first, and what happens when balances run low or go below zero.

Credit allocations

A customer’s balance is usually made up of several allocations rather than one single bucket. New allocations can be created when:

• A customer buys prepaid credits
• A recurring plan renews and includes a fresh allowance
• You manually grant bonus or promotional credits

Each allocation is tracked independently. That matters because different allocations can have different:

• Expiry dates
• Rollover windows
• Sources, such as purchased credits versus promotional credits

For example, a customer might have:

• 10,000 purchased API credits for their monthly plan
• 1,000 promotional API credits from a launch offer
• 500 rolled-over API credits from the previous period

Paid combines the usable portion of those allocations into the balance you see through the API and in the dashboard.

How credits are granted

Prepaid purchases

You can sell usage in advance by attaching credits to a product or plan. When the customer purchases that item, Paid creates a new credit allocation for them.

This is useful when you want customers to:

• Buy a bundle of usage before they consume it
• Start each billing cycle with a fresh allowance
• Top up when they run low

Included credits on recurring plans

Recurring plans can include a credit allowance as part of the subscription. For example:

• $99/month includes 1,000 API Credits
• $499/month includes 50,000 Messages

On each renewal, Paid grants the next allocation for that billing period based on your plan configuration.

Manual top-ups and promotions

You can also add credits outside the normal billing flow, for example:

• Goodwill credits after a support incident
• Promotional launch credits
• A manual top-up sold by your sales or support team

These create separate allocations, which means they can have their own expiry date and may be consumed before purchased credits depending on their configuration.

When credits become available

Credits can become available at different points depending on how your pricing is configured:

• On activation: credits are usable as soon as the order or billing period starts
• On payment: credits stay pending until the related invoice is paid

This lets you decide whether customers can use credits immediately or only after payment is collected.

If you activate an order with a startDate in the past, Paid backfills credit grants and invoices for every elapsed period at activation. See Backdated order activation for the full contract.

How credits are consumed

When Paid receives a usage event tied to a credit-backed pricing model, it deducts credits automatically from the customer’s available allocations.

Paid applies credits in a predictable order:

1. Promotional or manually granted credits are usually consumed before purchased credits
2. Allocations that expire sooner are consumed before those that expire later
3. If there is still a tie, older allocations are consumed first

This helps customers use the credits most at risk of expiring before longer-lived balances.

What happens when credits run out

If usage exceeds the customer’s available balance, Paid can continue recording usage and treat the difference as overage, depending on your pricing setup.

From the customer’s perspective:

• Their available balance reaches zero
• New usage can still be accepted
• The excess can later be billed as overage

This is useful if you do not want product usage to stop the moment a balance is exhausted.

Top-ups after exhaustion

When a customer has already exhausted their credits, the effect of a top-up depends on how you apply it.

New top-up allocation

If you add a new top-up as a fresh credit grant, the customer gets a new usable balance immediately.

Example:

• Customer had 100 credits
• Customer used 200
• You add a new top-up of 50

Result:

• The earlier deficit still exists historically
• The new 50 credits are available to spend right away

This is the right model for a true top-up purchase or goodwill grant.

Adjusting an earlier allocation

If instead you increase an earlier allocation retroactively, the added credits first reduce the existing deficit. In that case, the customer may see little or no newly available balance immediately.

This is the right model when you are correcting or resizing a prior grant rather than giving the customer a fresh top-up.

Rule of thumb

Use:

• A new credit grant when you want the customer to receive new spendable credits now
• An adjustment to an existing grant when you want to correct the historical allocation itself

Rollover

Credits can optionally roll forward after a billing period ends.

With rollover enabled:

• Unused credits can remain available after the original period closes
• You can cap how much rolls over
• You can define how long rolled-over credits stay valid

Example:

• A monthly plan includes 1,000 credits
• Up to 200 unused credits roll over
• Rolled-over credits expire after 30 days

This gives customers flexibility without letting unused balances accumulate forever.

Querying balances

Use the API to retrieve a customer’s current balance by credit currency.

This is useful for:

• Showing remaining credits in your product
• Preventing an action when the balance is too low
• Triggering low-balance alerts or top-up prompts

The balance response is grouped by credit currency and includes a recipient field. recipient tells you whether the balance applies to:

• organization: one shared balance for the whole customer account
• seat: a balance that is scoped to an individual seat-based allocation

1
import { PaidClient } from '@paid-ai/paid-node';
2
3
const client = new PaidClient({ token: 'YOUR_API_KEY' });
4
5
const balances = await client.customers.getCreditBalances('cus_abc123');
6
7
for (const balance of balances.data) {
8
  console.log(`${balance.currencyName}: ${balance.available} available`);
9
}

Example response:

1
{
2
  "data": [
3
    {
4
      "creditsCurrencyId": "cc_abc123",
5
      "currencyName": "API Credits",
6
      "currencyKey": "api_credits",
7
      "available": 7500,
8
      "used": 2500,
9
      "total": 10000,
10
      "periodStart": "2026-03-01T00:00:00.000Z",
11
      "periodEnd": "2026-03-31T23:59:59.999Z",
12
      "rolloverEndDate": null,
13
      "recipient": "organization"
14
    }
15
  ]
16
}

In most prepaid setups, organization is the right model because the whole customer account draws from the same pool. Use seat when each licensed seat should receive and consume its own allowance independently.