​

Split staging and production across subaccounts

Parent org (your company — owns billing, keys, operators)
 ├─ subaccount: staging    plan: growth   monthly cap: $500
 └─ subaccount: production plan: growth   monthly cap: unbounded

​

1. When to split

• Separate test, staging, and production traffic. One subaccount per environment keeps regression sends, soak tests, and live sends from competing on the same rate limit or wallet. The sibling multi-environment subaccounts page walks through the flat per-stage model; this guide is the migration recipe into it.
• Department-level billing. Each business unit gets its own child so spend lines can be invoiced or transferred per unit — the parent statement stays the single source of truth.
• Brand-level channels. A multi-brand org isolates one brand per subaccount so that sender IDs, WhatsApp templates, and AI configuration stay per brand and a leaked key on one brand can’t pivot across the rest.

​

2. Plan the tree

1. Senders and numbers scope to a subaccount, not the parent. When you assign a sender to a child, that sender is reachable only by the child’s keys. Plan explicitly which senders belong to every child — and expect to keep a “test sender” distinct from the production set.
2. Keys are per subaccount. A parent-scoped key mints, funds, and retires children; a child-scoped key operates only that child’s messaging. The tree is unambiguous about which key goes where.

​

3. Create the subaccounts

curl -X POST https://api.orbit.devotel.io/api/v1/subaccounts \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "payments-staging",
    "plan": "growth",
    "monthly_spend_cap_cents": 50000,
    "rate_limit_per_second": 50
  }'

​

4. Per-subaccount API keys

# staging worker
curl -X POST https://api.orbit.devotel.io/api/v1/subaccounts/sub_stage9x/api-keys \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "staging-worker", "scopes": ["messages:read", "messages:write"] }'

# production worker
curl -X POST https://api.orbit.devotel.io/api/v1/subaccounts/sub_prod7k2/api-keys \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "production-worker", "scopes": ["messages:read", "messages:write"] }'

• Which organization the key can see. A key minted on sub_stage9x calls /sms, /messages, analytics, and AI endpoints as that child — it cannot read the parent’s tree or the sibling’s data. A 403 on POST /api/v1/subaccounts from a child key and a 404 on a child-scoped read from a parent key are the expected isolation failure modes and a feature, not a bug.
• What that key can do. Scope it down to messages:read + messages:write (or whichever family the surface needs) so a leaked key is bounded. See Scope API keys per integration for the scope-by-surface matrix.

​

5. Connection modes per child

• Both children inherit the platform default. Simplest; everything meters at standard rates against the parent wallet.
• Production on a BYO connection, staging on platform default. Set the BYO row on the parent once (it covers every child), then constrain staging’s spending by its monthly cap and rate limit so the BYO carrier never sees test traffic ramp.

​

6. Apply AI configuration per subaccount

curl -X PUT https://api.orbit.devotel.io/api/v1/subaccounts/sub_stage9x/ai-config \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false, "provider": null, "comped": true }'

​

7. Move traffic with a blue/green cut

1. Verify the children are healthy. Confirm each child shows active under Settings → Subaccounts, that its scoped key mints, and that a smaller-than-usual test send succeeds on the staging child.
2. Dual-send for a full business day. Point your integration’s staging traffic at the staging child’s key. Keep live traffic on the existing key. Read GET /api/v1/subaccounts/usage-rollup and confirm the staging line is growing and is the only line that grows.
3. Cut production to the new key. Deploy the integration with the production child’s key. Watch the parent’s usage rollup: the production line ticks up as the old line ticks down. A falling line where you expect a rising one means a key is pointing at the wrong child.
4. Quiesce the old keys. Leave the parent-scope integration key in place for one more day for emergency rollback, then rotate it out. Stale keys are the most common production leak after a cut — a worker that still has the old credential keeps billing against the old wallet, invisible from the new subaccount’s dashboard.

​

8. Bill each subaccount separately

• Per subaccount usage. GET /api/v1/subaccounts/{id}/usage returns one child’s metered usage, and GET /api/v1/subaccounts/usage-rollup folds the whole tree. That is your staging-vs-production statement.
• AI spend per child. Open Billing → Usage → AI in the dashboard or call GET /api/v1/usage/ai scoped per subaccount — the surface is the same shape as the org-wide AI usage split, just on the child.
• Intra-environment chargeback. When one child splits its own spend further (say, stage_regression vs stage_ux), the metadata.cost_center tag still applies inside the child — tag at send time, read the rollup, and the parent’s per-child line stays as the outer wallet boundary.

• GET /api/v1/billing/statements — monthly summaries
• GET /api/v1/billing/statements/:period — a month’s detail rows
• GET /api/v1/billing/statements/:period/download — CSV or JSON export per period

​

9. Common pitfalls

• Channel leakage. Senders not scoped to a child are unreachable from it (the “404 on a child-scoped read” isolation failure) — but senders left on the parent keep leaking traffic there. Audit every sender after the split and move the test senders explicitly; the staging-versus-production sender split is what makes the billback real.
• Template sharing does NOT cross subaccounts. A WhatsApp or SMS template approved on one child is not visible to the sibling. Recreate the template on each child, or plan a shared template review pass per child as part of onboarding. Subaccounts API covers the per-child template surface.
• Billing surprises. Two places staging invoices itself into production: a stale pending child never finalized (it cannot serve traffic but also shows in the list — either finalize it or delete it), and a stale parent-scoped integration key still bound in a worker. The first shows in Settings → Subaccounts with status pending; the second shows up as a usage line on the parent rollup when every other line is where you expect it.
• Budget ceilings. The child’s monthly_spend_cap_cents and its rate limit are what they say they are — staging does not borrow from production’s headroom. A staging regression run that needs headroom you did not plan needs a cap raise, not an emergency credit transfer.

​

See also

• White-label subaccounts — the reseller variant when the children are your customers, not your own environments
• Multi-environment subaccounts — the per-stage model this recipe migrates you into
• New subaccount wizard — dashboard walkthrough of the create flow
• Per-channel connection mode — BYO vs platform default inheritance per channel
• Per-subaccount AI configuration — per-child AI enable/provider/comped
• Cost-center chargeback — the metadata.cost_center tag inside a child
• AI usage split — per-agent/model/channel AI attribution read
• Subaccounts API — endpoint catalog