> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routerbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing

> Check your USD balance, top up via Stripe, and view transaction history.

RouterBase billing is denominated in **USD**. Per-call model costs are reserved at submit time and charged on success; failed generations release the reservation. Stripe top-ups add to it.

## Balance lifecycle

```
submit gen     reserve  (held += cost,  available -= cost,  credits unchanged)
   │
   ├── success → charge   (credits -= cost, held -= cost,  transactions row written)
   │
   └── failure → release  (held -= cost,  credits unchanged, no transactions row)
```

## Get Balance

```
GET https://routerbase.com/api/v1/billing/balance
```

```json theme={null}
{
  "credits": 42.50,
  "held": 1.20,
  "available": 41.30,
  "currency": "USD"
}
```

| Field       | Meaning                                                                  |
| ----------- | ------------------------------------------------------------------------ |
| `credits`   | Raw account balance. Only top-ups and completed charges move this.       |
| `held`      | Sum of pending generation reservations. Not yet deducted from `credits`. |
| `available` | `credits − held`. The amount you can spend on a new request.             |
| `currency`  | Always `USD`.                                                            |

<Info>
  Use `available` as the spendable balance. A submit will be rejected with `402 Insufficient Credits` when the request cost exceeds `available`, even if `credits` alone would cover it.
</Info>

## Top Up

Top-ups happen through the billing page's payment flows (card via Stripe, or PayPal), which confirm the payment server-side before crediting `credits`. There is no direct top-up API endpoint — programmatic crediting is available only through [coupons](#coupons).

## Coupons

Coupons are prepaid credit codes. Redeeming one adds its value to your balance — a top-up without a card, recorded like any other transaction (`payment_method: "coupon"`).

<Info>
  Coupons are issued directly by RouterBase (promotions, credits, enterprise arrangements). To request one, contact us at [support@routerbase.com](mailto:support@routerbase.com).
</Info>

### Redeem a Coupon

```
POST https://routerbase.com/api/v1/billing/coupons/redeem
```

<ParamField body="code" type="string" required>
  The coupon code you received (e.g. `A1B2-C3D4-E5F6`).
</ParamField>

### Response

```json theme={null}
{
  "credited": 5.0,
  "currency": "USD",
  "balance": 42.50
}
```

| Field      | Meaning                                   |
| ---------- | ----------------------------------------- |
| `credited` | Amount this coupon added to your balance. |
| `currency` | Currency of the credit.                   |
| `balance`  | Your raw balance after the credit.        |

A coupon can be redeemed **once**.

| Status | Meaning                                                     |
| ------ | ----------------------------------------------------------- |
| `404`  | The code is not valid.                                      |
| `409`  | The code has already been redeemed, or is no longer active. |

<Note>
  You can also redeem a coupon from the **Billing** page in the dashboard — enter it in the "Redeem Coupon" box.
</Note>

## Transaction History

```
GET https://routerbase.com/api/v1/billing/transactions
```

Returns a paginated list of all top-ups and **completed** usage charges. In-flight reservations (`held`) are not listed here — they aren't transactions until the generation finishes.

### Query Parameters

<ParamField query="page" type="number">
  Page number. Default: `1`.
</ParamField>

<ParamField query="per_page" type="number">
  Results per page. Default: `20`.
</ParamField>

### Response

```json theme={null}
{
  "data": [
    {
      "id": "txn_01HXYZ",
      "credits": -0.05,
      "amount": 0.05,
      "payment_method": "usage",
      "status": "completed",
      "created_at": "2025-01-15T11:00:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "per_page": 20
}
```

| `payment_method`      | What it represents                                             |
| --------------------- | -------------------------------------------------------------- |
| `usage`               | A generation completed and was charged. `credits` is negative. |
| `stripe` (or similar) | A top-up cleared. `credits` is positive.                       |

## Balance Alerts

### Create Alert

```
POST https://routerbase.com/api/v1/billing/alerts
```

<ParamField body="threshold" type="number" required>
  Receive an email when `credits` drops below this amount.
</ParamField>

### Delete Alert

```
DELETE https://routerbase.com/api/v1/billing/alerts/{id}
```