> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpaygent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpaygent.com/_mcp/server.

# Credit Currencies

Credit currencies are **custom billing units** you define once and reuse across wallets, agent pricing, plans, and orders. Instead of exposing raw USD per API call, you can sell "Credits", "API Units", or "Compute Hours" — each mapped to a USD conversion rate for invoicing.

## Why credit currencies?

| Challenge                                           | How credit currencies help                     |
| --------------------------------------------------- | ---------------------------------------------- |
| Customers don't think in fractional cents per token | Package usage as familiar "credits"            |
| Prepaid packs and top-ups                           | Wallets hold balances in your currency         |
| Postpaid "use now, pay later"                       | Accrue credits, convert to USD at invoice time |
| Platform fee bundles                                | Grant 10,000 credits/mo with a subscription    |

---

## Create a credit currency

Sidebar → **Credit Currencies** → **Create currency**

| Field                       | Description                                                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Name**                    | Human-readable label (e.g. "Paygent Credits")                                                                 |
| **Code (key)**              | Unique identifier used in API, pricing, and wallets (e.g. `cx`, `Credits`) — **cannot change** after creation |
| **Description**             | Optional internal notes                                                                                       |
| **Default conversion rate** | USD value of **one** credit (e.g. `0.01` → 100 credits = \$1.00)                                              |
| **Type**                    | `credit` (default) or `entitlement` — label only; same wallet behavior                                        |

> **Warning**
>
> The **key** is referenced everywhere: agent indicator pricing, platform fee credit benefits, wallet APIs, and orders. Pick a short, stable code and use it consistently in your SDK integration.

---

## Where credit currencies are used

```
Credit Currencies (define once)
        │
        ├── Platform fee → Credit benefits (prepaid load)
        ├── Activity / Outcome indicator → CREDITS billing type
        ├── Customer wallet (prepaid or postpaid)
        └── Invoice line items (USD = credits × conversion_rate)
```

### 1. Platform fee credit benefits (prepaid)

On an agent or plan, under **Platform fee → Credits / Entitlement**:

* Select the credit currency key
* Set credits granted per billing period (e.g. 1,000/month)
* Optional refresh frequency (Monthly, Quarterly, Annually)

Credits post to the customer's **prepaid wallet** when the invoice is paid.

### 2. Indicator pricing (usage cost)

On **Agents → Step 3: Pricing → Activity/Outcome indicator**:

* Set billing type to **CREDITS**
* Select the same credit currency key
* Set **credits per indicator** — cost per usage event (or per metered unit if a billable metric is linked)

### 3. Customer wallets

Each customer holds one active wallet per `(customer, credit currency, organization)`:

* **Prepaid** — credits loaded upfront; usage debits `available_balance`
* **Postpaid** — usage accrues in `postpaid_used`; invoiced in USD at period end

Full wallet guide: [Credits & Wallets](/documentation/introduction/credits-and-wallets)

---

## Conversion rate

The conversion rate translates credits to USD for invoices and reporting:

```
USD amount = credits × conversion_rate
```

| Rate    | Meaning                                 |
| ------- | --------------------------------------- |
| `0.01`  | 1 credit = $0.01 → 100 credits = $1.00  |
| `0.002` | 1 credit = $0.002 → 500 credits = $1.00 |

* **Credit currency default** — suggested rate when creating wallets
* **Wallet override** — each wallet can store its own `conversion_rate` (set at wallet creation)

---

## Credit vs entitlement type

Both types behave identically at runtime. The `type` field is a **label** for dashboard display and balance API grouping:

| Type          | Typical use                          |
| ------------- | ------------------------------------ |
| `credit`      | Consumable usage units               |
| `entitlement` | Feature access or bundled allowances |

---

## Example: prepaid credit pack

1. Create currency `cx` with conversion rate `0.002`
2. Agent platform fee: grant **10,000 cx/month**
3. Indicator `inference`: **CREDITS**, 10 cx per call
4. Create order → wallet auto-created on first invoice
5. Customer pays invoice → 10,000 cx available
6. Each inference debits 10 cx until balance exhausted (or overage if enabled)

---

## Example: postpaid credits

1. Create currency `api_units` with rate `0.01`
2. **Do not** add platform fee credit benefits
3. Indicator `api-call`: **CREDITS**, 5 api_units per call
4. Manually create **postpaid wallet** for customer (dashboard)
5. Usage accrues → invoiced as USD at billing run

> **Warning**
>
> You cannot mix prepaid and postpaid for the same customer + currency. Create the wallet type you intend **before** the first invoice to avoid auto-creation of the wrong wallet type.

---

## Checklist

* ✓ Credit currency created with stable key and conversion rate
* ✓ Agent/plan indicators use **CREDITS** billing with matching key
* ✓ Prepaid: platform fee credit benefits configured + order with wallet settings
* ✓ Postpaid: postpaid wallet created manually + indicator credits per signal set
* ✓ SDK sends usage events — wallet debits happen at billing time

**Related:** [Credits & Wallets](/documentation/introduction/credits-and-wallets) · [Prepaid Wallets API](/api-reference/prepaid-wallets-api) · [Postpaid Wallets API](/api-reference/postpaid-wallets-api)