Core Concepts

Credits & Billing

How pricing, credits, the monthly pool, and refunds work.

Orders are paid for in credits. Credits are only ever spent on launch — creating, editing, and reading orders is free.

Credits and money

1 credit = 1 USD cent. Every monetary value in the API is an integer in minor units (USD cents), e.g. price: 28800 — that order costs 28800 credits. The API is always USD.

Launch responses return both figures so you can reconcile against your own books:

  • price — the list price in USD cents.
  • credits_charged — the integer credits debited (may differ from the list price after org discounts or a first-order bonus).

Pricing

Each placement is priced from its quality tier, with +20% added for each of content_guidelines and domain_specifications (they stack). The order price is the sum of its placements. Both the order and each placement return a live price_breakdown itemizing the base band and every modifier, so the total is always fully explained. Prices are recomputed on every read — you never rely on a cached number.

The monthly credit pool

Each API key draws from a monthly credit pool on top of your account balance:

  • The pool has a per-key monthly limit (set in Settings → API Keys). A limit of 0 means unlimited.
  • The window is the calendar month in UTC and resets on the 1st. The period is computed per spend, so a missed reset never leaves a stale window open.
  • The pool is funded by your underlying account balance; you need available balance for a launch to settle.

Charge lifecycle (reserve → settle / release)

Launch charges are two-phase so you are never charged for a launch that fails:

  1. Reserve — before the order is launched, the launch amount is reserved against the key’s monthly pool. If the reservation would exceed the monthly limit, the request stops here with 402 (OVER_CREDIT_LIMIT) and no order is launched.
  2. Settle — on a successful launch, the reservation is settled and your balance is debited by the actual credits_charged.
  3. Release — if the launch fails downstream, the reservation is released and you are not charged.

402 OVER_CREDIT_LIMIT means the launch would exceed the key’s monthly pool or you lack sufficient balance. Raise the per-key limit, top up the balance, or wait for the monthly reset.

Refunds

Credits are charged on launch and refunded through Respona’s standard refund flow — for example, when a placement is REJECTED. Refunds surface as a REFUNDED status on the placement or order. Track them by polling the resource.

Degraded mode

The launch path fails closed: if the billing/idempotency infrastructure is unavailable, launch returns 503 rather than risk an over-spend or a duplicate charge. Reads and draft edits are unaffected. See Errors.