Billing

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

{
  "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`.

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.

Top Up

POST https://routerbase.com/api/v1/billing/topup

Initiate a USD purchase via Stripe. The amount is added to credits once Stripe confirms the payment.

number

required

Amount in USD to add to your balance.

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").

Coupons are issued directly by RouterBase (promotions, credits, enterprise arrangements). To request one, contact us at [email protected].

Redeem a Coupon

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

string

required

The coupon code you received (e.g. A1B2-C3D4-E5F6).

Response

{
  "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.

You can also redeem a coupon from the Billing page in the dashboard — enter it in the “Redeem Coupon” box.

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

number

Page number. Default: 1.

number

Results per page. Default: 20.

Response

{
  "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

number

required

Receive an email when credits drops below this amount.

Delete Alert

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

Get Started

API Reference

Balance lifecycle

Get Balance

Top Up

Coupons

Redeem a Coupon

Response

Transaction History

Query Parameters

Response

Balance Alerts

Create Alert

Delete Alert

​Balance lifecycle

​Get Balance

​Top Up

​Coupons

​Redeem a Coupon

​Response

​Transaction History

​Query Parameters

​Response

​Balance Alerts

​Create Alert

​Delete Alert

Balance lifecycle

Get Balance

Top Up

Coupons

Redeem a Coupon

Response

Transaction History

Query Parameters

Response

Balance Alerts

Create Alert

Delete Alert