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.

Controlling how many credits a signal consumes

There are three ways to control the number of credits deducted by a signal:

Fixed credit cost. Set the credit cost on your product’s pricing rule (e.g., credit cost = 1). Every matching signal deducts exactly that amount. This is the simplest model and works well when every action has the same cost.

Dynamic quantity from the signal. Configure your pricing rule with a quantity mapping that reads from the signal’s data object (e.g., map quantity to $.quantity). Then pass the quantity value in each signal. The formula becomes quantity x creditCost. For example, if the pricing rule has credit cost 1 and the signal sends quantity: 5, that signal deducts 5 credits.

1
await paid.signals.createSignals({
2
  signals: [
3
    {
4
      eventName: "workflow_run",
5
      customer: { externalCustomerId: "cus_acme" },
6
      attribution: { externalProductId: "automation" },
7
      data: { quantity: 5 },
8
    },
9
  ],
10
});

Bracketed prepaid credits. For non-linear credit costs, use the bracketed prepaid credits pricing model. This lets you define quantity ranges that each map to a flat credit amount. For example, processing 1 to 10 pages might cost 1 credit, while 11 to 50 pages costs 5 credits. The bracket is selected based on the signal’s quantity value.

Tracking credit consumption by user

Credit balances are managed at the customer (organization) level, but you can attribute consumption to individual users within a customer account. Include external_user_id in the signal’s data field, matching the external ID of a user created via the user management API:

1
await paid.signals.createSignals({
2
  signals: [
3
    {
4
      eventName: "chat_message",
5
      customer: { externalCustomerId: "cus_acme" },
6
      attribution: { externalProductId: "chatbot" },
7
      data: { quantity: 1, external_user_id: "usr_jane_doe" },
8
    },
9
  ],
10
});

When Paid processes a signal with external_user_id, it resolves the user and their seat assignment. If the user occupies a seat with seat-scoped credit balances, the credit spend is deducted from that seat’s balance rather than the organization pool. If no seat is found, credits are deducted from the organization balance as usual.

All fields in the data object are also stored with the signal and queryable through the analytics API, so you can break down usage by user, team, or any other dimension you include.

Seat-based plans can grant credits either to the organization (shared pool) or to individual seats (per-user balance), depending on how the credit benefit is configured. See Examples of plans with included credits for both patterns.

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.