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

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