Skip to main content
With rebilling on, a sub-account pays for its own calls from its own wallet, at the rate you charge the client, and the client’s card tops that wallet up. This guide sets it up over the API. Every figure it touches is explained in Balances, spend and sub-account wallets.

​
Prerequisites

  • An API key from an agency admin with the billing:write scope. To charge the client’s card in the same step, the key also needs billing:charge.
  • Your plan includes client rebilling, and Stripe Connect is connected for your agency. Without either, every sub-account change answers CAPABILITY_NOT_AVAILABLE or STRIPE_NOT_CONNECTED and nothing changes.
  • The client exists as a customer on your connected Stripe account with a working card. Create customers and add cards in the dashboard; the API never takes card details.
  • The sub-account’s locationId, from List sub-account wallets.

​
Step 1: Turn rebilling on

Send the client rate and the Stripe customer to Update sub-account rebilling:
This links the customer, sets clientRatePerMinute and, when you include it, sets autoRecharge, all or nothing. If any step fails, the sub-account goes back to exactly what it had and the answer says why, for example NO_USABLE_CARD when the customer has no working card, or PAYMENT_METHOD_SELECTION_REQUIRED when it has several and no default. A rate above $10 a minute needs confirmHighRate: true, so a typo cannot price a client out by accident.

​
Step 2: Charge a first top-up

A freshly rebilled sub-account has an empty wallet. To turn rebilling on and charge the client in one step, use Enable rebilling with a charge instead of step 1, with an Idempotency-Key header:
The settings are saved first and the card charged last. A declined card puts every setting back.
The minutes a sub-account buys come out of your agency wallet. On a self-serve agency, a charge bigger than the minutes your wallet holds tops your wallet up first by charging your own billing card, so one call can charge two cards. If the client’s card then fails, that top-up of your own wallet stands. If your wallet cannot be topped up, the call is refused before the client’s card is touched.Name thresholdUSD and rechargeAmountUSD when you switch auto-recharge on. Left out on a sub-account that has never had them, they fall back to 50and50 and 200, and that second figure is what the client’s card is charged each time.
If Stripe cannot say whether the payment went through, the answer is PAYMENT_RECONCILIATION_REQUIRED with rebillingLeftOn: true: nothing is rolled back, because the money may have moved. To top up later, use Charge a sub-account. Reuse an Idempotency-Key only to retry the same charge; a retry returns the first answer and charges nothing.

​
Step 3: Decide what happens when the wallet runs dry

With Credit Guard on, the sub-account stops its own calls when its wallet is empty. With it off, your wallet pays for those calls. Set it on many sub-accounts at once with Update Credit Guard for sub-accounts.

​
Turning rebilling off

Send { "enabled": false } to the same rebilling operation. In one step the sub-account’s unused minutes return to your wallet at what they cost you, its auto-recharge goes off and its Stripe customer is unlinked. It is refused with PENDING_CREDITS_EXIST while a client payment is waiting for credit.
Minutes the client paid for become your credit. Nothing is refunded to the client, and the API cannot refund them: settle up with the client yourself.

​
Next steps