Buy a plan
Buy a rate bucket for your agency wallet.
A purchase is charged now on your default billing card, whatever your auto-recharge mode or setting: it answers PAID (201) when the minutes are in your wallet, CREDIT_PENDING (202) when your card was charged and the minutes are being added (within about a minute, the usual answer), or PROCESSING (202) while Stripe finishes the payment. Your auto-recharge mode applies only to automatic recharges. Every answer says what happened in message, and a refusal says nothing was charged. A declined card leaves nothing behind.
Charges a card now. Needs the billing:charge scope, which billing:write does not include, and an Idempotency-Key header: a retry with the same key returns the first answer instead of charging again. Limited to 10 charge calls a minute per API key (5 from one address), answered 429 beyond that; wait for RateLimit-Reset and retry with the same key. Not available over MCP.
Allowed customer roles: agency_admin. The agency is the one the credential belongs to.
Required API key scope: billing:charge.
Authorizations
Send your API key as Authorization: Bearer YOUR_API_KEY.
Headers
Required. A unique value per request, 8 to 255 visible characters. Reuse it only to retry the same request. A request that finished, with a success or a refusal such as a declined card, answers a retry with its first answer and idempotentReplay: true, and nothing runs or is charged again: once the card is fixed, try again with a new key. After a 503 that says nothing was changed, the same key runs the request again. After a 500, or any other answer whose outcome is not known, the same key answers 409 IDEMPOTENCY_OUTCOME_UNKNOWN: read the wallet back, then use a new key.
8 - 255Body
The plan to buy.
