Credits & billing
Every endpoint is priced in credits. Your account holds two separate balances:
- Subscription credits: allocated by an active plan at the start of each billing period, and expiring at the end of that period.
- Prepaid credits: bought in packages and carried forward.
Spending order
Subscription credits are consumed first; prepaid credits cover the remainder. With 40 subscription credits and 100 prepaid credits, a 50-credit call is charged like this:
| Balance | Before | Charged | After |
|---|---|---|---|
| Subscription credits | 40 | 40 | 0 |
| Prepaid credits | 100 | 10 | 90 |
The usage record shows that 40 credits came from the subscription allocation and 10 from prepaid credits. The same split is returned in the X-Clankerbay-Credits-* response headers.
How balances stay correct
- Every change (purchase, allocation, usage, expiry, refund, adjustment) is an entry in an append-only ledger. Balances are derived from it and reconciled daily.
- The gateway reserves credits atomically before calling a provider, so two simultaneous calls can never both spend the same last credits, even across many gateway instances.
- Each billable call is written to a durable journal before the response is returned, then batched into the database. A gateway crash or restart cannot lose a charge.
- Credits are only added after Stripe confirms payment through a verified webhook, never from a browser redirect, and each Stripe event is processed exactly once.
Subscriptions
- Upgrade: immediate. You pay the prorated difference and receive the additional credits for the current period.
- Downgrade: takes effect at the next renewal.
- Cancel: the plan stays active until the end of the period; remaining subscription credits are usable until then.
- Failed payment: the subscription becomes past due; no new credits are allocated until payment succeeds.
Refunds and disputes
Refunding a prepaid purchase reverses the corresponding unspent credits. Credits already spent cannot be reversed. A chargeback freezes the purchase's remaining credits until it is resolved.
Invoices
Every payment produces an invoice in Billing history, downloadable at any time.