Skip to main content

​
The reseller wallet funding model

Money in a reseller family lives in wallets, and there is exactly one wallet per organization. This page is the model for that money: how funds enter the family, how the parent pushes credits down to subaccounts, what monthly_spend_cap_cents refuses when a child hits it, and what an empty or suspended child’s money looks like. Read it before you design the finance side of a resale; the how-to mechanics live in White-label subaccounts and the endpoint catalog in the Subaccounts API.

​
Section 1 — One wallet per org, N wallets per family

Every organization — the parent and each subaccount — holds its own prepaid wallet, denominated in cents. The family shares one tenant schema, but money sits at the org layer, not the tenant layer:
Keep the two layers distinct:
  • Tenant layer (data). The parent and all its subaccounts share one tenant schema; siblings are separated by row-level ownership gates, not by databases. The worked example is in Tenant isolation, Section 3.
  • Org layer (money). Nothing is shared. Each wallet is an independent balance. West Clinic at $0 cannot draw on the parent's $500, and a suspended Delta keeps its $45.50 where siblings cannot reach it. A suspended or empty child never touches the parent’s balance.
There is no pooled family balance and no implicit overdraft from parent to child. If you want a child to send, its own wallet must hold the money.

​
Section 2 — The funding arc: parent to child, and only that direction

Funds enter the family where they enter the parent — top-ups and payment settlement, covered in Wallets, credits, and charges. From the parent, credits reach a child in exactly two ways, and both are parent-initiated:
  1. Seed at creation. POST /api/v1/subaccounts accepts an optional initial_credits_cents: a one-time seed deducted from the parent as the subaccount is provisioned. It is best-effort. If the parent cannot cover it, the subaccount is still created at $0 and you fund it afterwards with a transfer.
  2. Credit transfer. POST /api/v1/subaccounts/{id}/transfer-credits is the day-to-day lever. It requires the owner role on the parent organization; lesser roles on the parent are refused. The body takes amount_cents (an integer from 1 to 1,000,000 per call), an optional note that lands in the org audit trail, and an optional client_reference_id for retry safety.
A transfer carries four guarantees:
  • Atomic debit-then-credit. The parent’s debit and the child’s credit land as one operation. If the credit leg fails after the debit, the parent is restored; a failed transfer never leaves money in flight.
  • Retry safety. Two calls with the same parent, child, amount, and client_reference_id collapse into a single debit: the second is recognized as a retry of the first. Without a reference, each call is a distinct transfer and debits the parent again, so retrying clients should always send one.
  • Solvency at the parent. If the parent wallet cannot cover amount_cents, the call is refused with 402 INSUFFICIENT_BALANCE and neither wallet changes. A child id that does not exist or does not belong to the caller is a 404.
  • A ledger row on each book. The parent’s transaction ledger records a debit referencing the transfer to that subaccount; the child’s records a credit referencing the transfer from the parent. Both rows land in the same ledger your top-ups and usage debits write to, so dashboard balances show the transfer immediately, and the response returns both new balances as parent_balance_cents and child_balance_cents.
The arc runs strictly parent to child. There is no endpoint that moves credits child to parent or sibling to sibling. Credits a child does not spend stay the child’s; money never flows back up the tree on its own. Consolidating family revenue happens in your own billing flow, on the invoice lane, not in the wallets. The funding arc ends at the child wallet; what the child’s usage costs and how you mark it up for your end customer is the margin model, not this one.

​
Section 3 — Spend caps: what monthly_spend_cap_cents refuses

Each org carries its own monthly_spend_cap_cents: the most it may spend in a calendar month. The cap is a spend control, not a balance control. It is checked at the billing gate before an outbound send is allowed to cost anything, and it leaves the wallet itself alone. Two consequences follow:
  • Transfers into a capped child still land. Credits arriving from the parent are not spend by the child and do not count toward the child’s cap.
  • At the cap, the child’s sends are refused. Outbound stops at the gate, outwardly similar to the empty-wallet pause in Section 4 but with a different cause and a different recovery: the month rolling over, or you raising the cap. What counts as spend and how the month is measured is defined in Spend caps.
The cap stacks with the other outbound controls instead of replacing them. An operator pause flag, an empty-wallet pause, and a reached cap each refuse sends independently; whichever trips first wins. Billing burn rate is the read-side tool for predicting which ceiling a child hits first, cap or wallet.

​
Section 4 — The zero-balance child: parent full, child empty

An empty child behaves like any org that has run out of credit: its sends are refused with 402 INSUFFICIENT_BALANCE, its outbound is paused at the child’s scope, and nothing about the parent changes. The parent and every funded sibling keep sending normally. Worked example, the staging/production split from Staging and production subaccounts. The parent holds $500, the production child $120, and the staging child sits at $0 when a test campaign fires 10,000 messages: An empty staging child stops sending without touching production. That is the isolation the org layer buys you: a drained child is a contained event. Recovery is a single transfer from the parent, and topping the wallet back up re-enables the child’s outbound without a manual unpause.

​
Section 5 — Suspend and reactivate: the money rules

Three rules cover nearly every suspension question:
  • Credits do not move on suspension. Suspending a child pauses its operations, not its wallet: nothing is clawed back to the parent and nothing is redistributed to siblings. Reactivation returns the child to exactly the balance it had, as covered in Suspend and reactivate a subaccount.
  • Standing charges keep accruing. Time-based charges, such as number rentals, keep drawing on the suspended child’s wallet, so a suspended balance can still go down (Subaccounts console). A child that was funded at suspension can therefore reactivate empty and need a transfer before its sends pass.
  • The cap window is calendrical. Suspending mid-month neither pauses, extends, nor refunds the cap: spend recorded before the suspension still counts after reactivation, and the cap resets at the month boundary as usual.

​
Section 6 — Boundaries: the adjacent money models