Multi-environment subaccounts

Subaccounts are not only a reseller feature. A single organization can declare its own child organizations — one per environment (dev, staging, prod) or one per product line — and get per-subaccount wallets, spend caps, connection-scoped keys, and a spend-attribution structure that flat membership cannot express. Traffic and billing stay separated by design, without you maintaining three login environments. Every control in this guide is tenant-owned: nothing below changes how outbound traffic terminates. This guide covers the whole lifecycle — election, provisioning, funding, scope assignment, billing, and daily operations. Readers: platform engineers splitting one org into stages, or an org head splitting product lines.

1. The account after election

Provisioning follows the account operators you chose during signup. The creator of the organization becomes its owner; the people you invite into Settings → Team become the operators who administer subaccounts. Subaccount writes accept only owner or admin role tokens, so the election step of choosing operators lands here: subaccount management follows whoever you made an admin. See Team members, invitations, and roles if the operator list needs adjusting first — an environment subaccount inherits nothing about your member roster, and the parent’s admins are the people who can wire it.

2. Declare one subaccount per environment

One call per stage against the flat create endpoint. Reach for the plain POST /api/v1/subaccounts (or the one-shot POST /api/v1/subaccounts/provision) — both the reseller import flow and the channel connection modes pages build on the same pair:

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,
    "initial_credits_cents": 10000
  }'

The 201 body is the one every later step hangs off — the child id, the wallet state after the seed, and the cap echoed back:

201

{
  "data": {
    "id": "sub_9x4tqkz",
    "name": "payments-staging",
    "slug": "payments-staging",
    "plan": "growth",
    "subscription_status": "active",
    "monthly_spend_cap_cents": 50000,
    "initial_credits": { "transferred_cents": 10000 },
    "created_at": "2026-09-01T09:00:00Z"
  },
  "meta": {
    "request_id": "req_env_create_001",
    "timestamp": "2026-09-01T09:00:00Z"
  }
}

Only name is required; plan, cap, and initial funding are optional. Repeat once per environment so naming stays unambiguous: payments-dev, payments-staging, or product-a / product-b for a product-line split. Carry data.id (the sub_... child id) into every later path; initial_credits.transferred_cents confirms the seed landed in the child wallet.

3. Deploy stages

A subaccount per stage gives each environment its own wallet, budget, and isolation boundary:

Per-subaccount wallet — credits transfer between the parent’s wallet and the child’s wallet with POST /api/v1/subaccounts/{id}/transfer-credits. Traffic on the child draws only from the child’s balance.
Budget — monthly_spend_cap_cents on the child stops a stage from draining the parent wallet. Stage budgets are usually tighter than the production cap.
Plan and limits — seats and the rate limit follow the child, so a dev subaccount’s traffic ceiling does not compete with production callers.

The parent’s wallet is the feeder for every stage. When staging empties, another transfer tops it up; the parent’s remaining balance is unchanged until you move credits. A top-up is one call, and the response reports both balances after the move, so you reconcile without a second read:

curl -X POST https://api.orbit.devotel.io/api/v1/subaccounts/sub_9x4tqkz/transfer-credits \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 15000,
    "note": "September staging budget",
    "client_reference_id": "staging-2026-09"
  }'

200

{
  "data": {
    "transferred": true,
    "amount_cents": 15000,
    "parent_balance_cents": 225000,
    "child_balance_cents": 25000
  },
  "meta": {
    "request_id": "req_env_transfer_001",
    "timestamp": "2026-09-02T08:30:00Z"
  }
}

The child now holds its seed plus the top-up (10,000 + 15,000 = 25,000) and the parent shows the debit. Retrying with the same client_reference_id returns this result again instead of moving the credits twice.

4. Reuse stages through scoped keys

Inheritance means the scoping rules your integration already knows apply per subaccount too. A key minted on the parent administers the tree; a key minted on the child reaches only that child — one leak can’t pivot across environments. The scope-per-integration guide walks through which scope family each surface needs; on a child you mint the same narrow pair (messages:write + messages:read, e.g.) and your staging worker uses its own scoped key just as a production one does.

curl -X POST https://api.orbit.devotel.io/api/v1/subaccounts/sub_9x4tqkz/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"] }'

201

{
  "data": {
    "id": "apikey_7Km2qd",
    "key": "dv_live_sk_T4mWzK8qLpX2vN6bJcYd8fR2",
    "keyPrefix": "dv_live_sk_",
    "lastFourChars": "8fR2",
    "name": "staging-worker",
    "type": "secret",
    "mode": "live",
    "scopes": ["messages:read", "messages:write"]
  },
  "meta": {
    "request_id": "req_env_mint_001",
    "timestamp": "2026-09-02T08:35:00Z"
  }
}

data.key is the one-time plaintext — store it before you discard the response; later key lists show only keyPrefix and lastFourChars. scopes is the exact pair the worker holds, nothing more. Hand the returned key to the staging worker. A production worker gets a key minted on the production subaccount the same way — the pair never share credentials. Because the child-scope boundary sits at the key layer, you can rotate the stage key on a schedule without touching production.

5. Billing and attribution

A multi-environment tree gives you two attribution patterns at once; pick either or combine:

Payer/payee attribution — the parent’s org is the payer; each child is a payee. GET /api/v1/subaccounts/{id}/usage reads one child’s metered usage, and GET /api/v1/subaccounts/usage-rollup folds the whole tree, so the parent’s statement line-items per environment.
Chargeback per stage — finer tags still work: a metadata.cost_center on the send (see Cost-center chargeback) lets one environment split its own spend internally, e.g. stage_regression vs stage_ux, while the parent still sees one rollup line per child.

Read one child’s metered usage (trimmed body; the full field list lives in the Subaccounts API):

curl https://api.orbit.devotel.io/api/v1/subaccounts/sub_9x4tqkz/usage \
  -H "X-API-Key: dv_live_sk_your_parent_key"

200

{
  "data": {
    "subaccount_id": "sub_9x4tqkz",
    "credits_used": 1840,
    "messages_sent": 212,
    "calls_made": 0,
    "current_plan": "growth"
  },
  "meta": {
    "request_id": "req_env_usage_001",
    "timestamp": "2026-10-01T07:00:00Z"
  }
}

Fold the whole tree for a billing period — one line item per environment:

curl "https://api.orbit.devotel.io/api/v1/subaccounts/usage-rollup?period=2026-09" \
  -H "X-API-Key: dv_live_sk_your_parent_key"

200

{
  "data": {
    "period": "2026-09",
    "totals": { "credits_used": 21230, "messages_sent": 2410, "calls_made": 96 },
    "subaccounts": [
      {
        "id": "sub_9x4tqkz",
        "name": "payments-staging",
        "credits_used": 1840,
        "messages_sent": 212,
        "calls_made": 0
      },
      {
        "id": "sub_2mwce08",
        "name": "payments-prod",
        "credits_used": 19390,
        "messages_sent": 2198,
        "calls_made": 96
      }
    ]
  },
  "meta": {
    "request_id": "req_env_rollup_001",
    "timestamp": "2026-10-01T07:00:05Z"
  }
}

The payments-staging line matches the single-child read above, and totals is the sum of the lines — that reconciliation is what makes the rollup a statement, not a snapshot. Omit period to default to the current UTC month. Membership structure stays relevant here: the parent’s admins are the members who read both surfaces — see Team management for who can reach the billing endpoints when the operator list changes.

6. Operate the lifecycle

Day-to-day operation is the parts you exercise once the tree exists:

Subaccount-scoped vs tenant-scoped keys — a parent-scope key mints, funds, and retires children; a child-scope key does only the child’s messaging. Guard the integration by which scope the caller actually holds — a child key against POST /api/v1/subaccounts returns 403, and a key outside a child’s tree — a sibling environment’s key, or a parent key from another organization — returns 404 on that child’s reads, never an empty 200.
Wallet isolation — a child cannot see the parent’s balance; the parent’s remaining-credit figure only moves when you transfer. Stage top-ups are explicit calls, never automatic drain.
Organization-profile hygiene — when the parent’s profile changes (billing contact, organization name), the change lives on GET/PUT /api/v1/organization/profile; children inherit nothing by design, so environment display names and branding remain per-child even if you update the parent.

The two boundary outcomes, as error bodies. A child-scoped key cannot administer the tree:

curl -X POST https://api.orbit.devotel.io/api/v1/subaccounts \
  -H "X-API-Key: dv_live_sk_staging_worker_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "rogue-env" }'

403

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Subaccount writes require an owner or admin role on the parent organization.",
    "status": 403
  },
  "meta": {
    "request_id": "req_env_guard_403",
    "timestamp": "2026-10-02T10:12:00Z"
  }
}

And a key outside a child’s tree cannot read it:

curl https://api.orbit.devotel.io/api/v1/subaccounts/sub_9x4tqkz/usage \
  -H "X-API-Key: dv_live_sk_unrelated_org_key"

404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Subaccount not found for this organization.",
    "status": 404
  },
  "meta": {
    "request_id": "req_env_guard_404",
    "timestamp": "2026-10-02T10:12:20Z"
  }
}

Worked example: a dev org runs a staged campaign against a stage child while production runs against the primary. POST /api/v1/campaigns on stage’s key sends the regression traffic; the same call with the production child’s key — which is the production workspace — handles live traffic. The parent’s rollup shows one usage line per stage, and the spend cap on stage means a runaway test campaign cannot drain production’s wallet.

7. Create, fund, and mint in one script

When a pipeline provisions stages rather than a person, the first three writes collapse into a single run through the SDK’s escape hatch (the same pattern as the CDR export guide):

Node.js

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

// 1. Declare the staging subaccount — cap and seed credits are optional.
const { data: child } = await orbit.request<{
  id: string;
  initial_credits: { transferred_cents: number };
}>("POST", "/subaccounts", {
  name: "payments-staging",
  plan: "growth",
  monthly_spend_cap_cents: 50000,
  initial_credits_cents: 10000,
});

// 2. Top the child wallet up from the parent.
const { data: topUp } = await orbit.request<{
  parent_balance_cents: number;
  child_balance_cents: number;
}>("POST", `/subaccounts/${child.id}/transfer-credits`, {
  amount_cents: 15000,
  note: "September staging budget",
  client_reference_id: "staging-2026-09",
});

// 3. Mint the scoped worker key — the plaintext returns exactly once.
const { data: workerKey } = await orbit.request<{
  key: string;
  scopes: string[];
}>("POST", `/subaccounts/${child.id}/api-keys`, {
  name: "staging-worker",
  scopes: ["messages:read", "messages:write"],
});

console.log(child.id, topUp.child_balance_cents, workerKey.key);

Hand workerKey.key to the staging worker’s secret store in the same run; from then on the worker authenticates as the child, never as the parent.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

Multi-environment subaccounts: dev, staging, prod, and product-line isolation

Multi-environment subaccounts

1. The account after election

2. Declare one subaccount per environment

3. Deploy stages

4. Reuse stages through scoped keys

5. Billing and attribution

6. Operate the lifecycle

7. Create, fund, and mint in one script

See also

​Multi-environment subaccounts

​1. The account after election

​2. Declare one subaccount per environment

​3. Deploy stages

​4. Reuse stages through scoped keys

​5. Billing and attribution

​6. Operate the lifecycle

​7. Create, fund, and mint in one script

​See also

Multi-environment subaccounts

1. The account after election

2. Declare one subaccount per environment

3. Deploy stages

4. Reuse stages through scoped keys

5. Billing and attribution

6. Operate the lifecycle

7. Create, fund, and mint in one script

See also