> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# The reseller wallet funding model: one wallet per org, funded parent-down

> Where a reseller family's money lives and how it moves — each org holds its own wallet, the parent funds subaccounts through owner-only credit transfers, monthly_spend_cap_cents caps child spend, and suspension pauses sending without moving credits.

# 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](https://docs.orbit.devotel.io/guides/subaccounts-reseller.md) and the endpoint catalog in the [Subaccounts API](https://docs.orbit.devotel.io/api-reference/subaccounts.md).

## 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:

```text theme={null}
Parent organization wallet                  $500.00
 ├── Acme Retail wallet                     $120.00
 ├── Delta Logistics wallet (suspended)      $45.50
 └── West Clinic wallet (empty)               $0.00
```

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](https://docs.orbit.devotel.io/concepts/tenant-isolation.md).
* **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](https://docs.orbit.devotel.io/concepts/wallets-credits-and-charges.md). 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](https://docs.orbit.devotel.io/billing/spend-caps.md).

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](https://docs.orbit.devotel.io/concepts/billing-burn-rate.md) 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](https://docs.orbit.devotel.io/guides/subaccount-staging-production-split.md). The parent holds $500, the production child $120, and the staging child sits at \$0 when a test campaign fires 10,000 messages:

| Wallet | Before | After the staging blast | Why |
| - | - | - | - |
| Parent | \$500.00 | \$500.00 | The staging blast stops at the staging wallet; the parent is never debited. |
| Production child | \$120.00 | \$120.00 minus its own usage | Sibling spend is gated by org ownership; it is not pooled. |
| Staging child | \$0.00 | \$0.00 | Every send is refused with `402`; the blast fails fast and costs nothing. |

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](https://docs.orbit.devotel.io/guides/subaccount-lifecycle-suspend-reactivate.md).
* **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](https://docs.orbit.devotel.io/guides/subaccounts-console.md)). 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

* **Reseller margin and tax** marks up rated amounts on billing documents. It is the invoice lane and it never moves a wallet: [Reseller margin and the tax pipeline](https://docs.orbit.devotel.io/concepts/reseller-margin-and-tax-pipeline.md).
* **eSIM resale** bills on a separate model with its own entitlements: [eSIM reseller billing](https://docs.orbit.devotel.io/concepts/esim-reseller-billing-model.md).
* **Wholesale reconciliation** of your rated usage against carrier CDRs is [CDR export and billing reconciliation](https://docs.orbit.devotel.io/billing/cdr-export-billing-reconciliation.md).
* **Wallet mechanics** — currency conversion, charge types, top-ups — are [Wallets, credits, and charges](https://docs.orbit.devotel.io/concepts/wallets-credits-and-charges.md).

## Related pages

* [White-label subaccounts](https://docs.orbit.devotel.io/guides/subaccounts-reseller.md) — provision, fund, brand, and retire the nodes of the family.
* [The subaccount organization model](https://docs.orbit.devotel.io/concepts/subaccount-organization-model.md) — the org tree this money model sits on.
* [Wallets, credits, and charges](https://docs.orbit.devotel.io/concepts/wallets-credits-and-charges.md) — the wallet mechanics beneath the funding arc.
* [Spend caps](https://docs.orbit.devotel.io/billing/spend-caps.md) — the cap lever in operator form.
* [Billing burn rate](https://docs.orbit.devotel.io/concepts/billing-burn-rate.md) — predict which ceiling a child hits first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.