Credits

Introduction

Credits let you offer prepaid balances to customers. Instead of billing purely on usage after the fact, you can sell credit bundles upfront and deduct from them as your AI agents perform work.

A typical credits workflow:

1. Create credit currencies to represent different unit types (e.g., “API Credits”, “Compute Hours”)
2. Attach credit benefits to products so that orders grant credits to customers
3. Query balances via the API to enforce limits or display remaining credits in your app

Prerequisites

• A Paid API key and the Paid SDK installed in the service that checks balances or sends signals.
• A credit currency configured in Settings > Credit currencies.
• A product or plan with a credit benefit, plus an active order or checkout-completed purchase that grants credits to the customer.
• Signals that match the product’s credit-backed pricing rule if you want Paid to deduct credits automatically.

Core Concepts

Credit Currencies

A credit currency defines a unit of value. Each organization can have multiple currencies for different billing dimensions.

Credit Balances

A balance represents how many credits a customer has for a given currency. Balances are grouped by:

• Currency: which credit currency the balance is for
• Recipient: whether credits belong to the organization (shared across all users) or a specific seat

Each balance includes:

Querying Credit Balances

Use the API to check a customer’s current credit balances. This is useful for:

• Enforcing credit limits before performing work
• Displaying remaining balances in your app
• Building low-balance alerts

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} / ${balance.total} available`);
9
}

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
}

The customer ID parameter accepts both display IDs (cus_xxx) and UUIDs.

Listing Credit Currencies

Retrieve all credit currencies configured for your organization:

1
const currencies = await client.credits.listCurrencies();
2
3
for (const currency of currencies.data) {
4
  console.log(`${currency.name} (${currency.key})`);
5
}

To include archived currencies, pass includeArchived=true:

$
curl -X GET "https://api.agentpaid.io/api/v2/credits/currencies?includeArchived=true" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Example: Enforcing Credit Limits

A common pattern is to check a customer’s credit balance before performing work:

1
async function performWork(customerId: string, creditsNeeded: number) {
2
  const balances = await client.customers.getCreditBalances(customerId);
3
4
  const apiCredits = balances.data.find((b) => b.currencyKey === "api_credits");
5
6
  if (!apiCredits || apiCredits.available < creditsNeeded) {
7
    throw new Error("Insufficient credits");
8
  }
9
10
  // Proceed with the work. Credits will be deducted
11
  // automatically when the corresponding signal is processed
12
  await doWork();
13
}

Dynamic Credit Consumption

By default, each signal deducts the fixed credit cost defined in your product’s pricing rule. To consume a variable number of credits per signal, configure your pricing rule with a quantity mapping that reads from signal data, then pass the quantity value in each signal.

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

With a quantity mapping configured, the credit deduction becomes quantity x creditCost. If the credit cost is 1 and the signal sends quantity: 5, that signal deducts 5 credits. Without the mapping, every signal deducts the fixed credit cost regardless of what you send in data.

This is useful when different actions consume different amounts of credit. For example, a simple query might cost 1 credit while a complex multi-step workflow costs 10.

See First signals for full examples in all SDKs and How credit balances work for the complete set of consumption strategies.

Setting Up Credits

To configure credits for your organization:

1. Navigate to Settings in the Paid dashboard
2. Create a credit currency with a name and key
3. Add credit benefits to a product’s pricing configuration
4. Create an order for a customer. Credits are granted when the order activates

Once credits are granted, you can query balances via the API as shown above.