Subaccounts API — worked reseller samples - Devotel Orbit Documentation

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": "Rahal Industries" }'

{
  "data": [
    {
      "id": "org_sub_rahal_00x9",
      "name": "Rahal Industries",
      "slug": "rahal-industries",
      "subscription_status": "active",
      "plan": "growth",
      "created_at": "2026-08-25T10:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_sub_list_001",
    "timestamp": "2026-08-25T10:00:00Z",
    "cursor": null,
    "has_more": false,
    "total": 1
  }
}

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": "Rahal Industries" }'

{
  "data": [
    {
      "id": "org_sub_rahal_00x9",
      "name": "Rahal Industries",
      "slug": "rahal-industries",
      "subscription_status": "active",
      "plan": "growth",
      "created_at": "2026-08-25T10:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_sub_list_001",
    "timestamp": "2026-08-25T10:00:00Z",
    "cursor": null,
    "has_more": false,
    "total": 1
  }
}

Real envelopes for the generated `{ data: {} }` shells

The numbered ops in this section fill in the response envelope the page’s autogen blocks render as {}. Each opener names its route so the generator keeps this body across rebuilds (see comment block above the lifecycle).

1. List subaccounts

GET /api/v1/subaccounts

{
  "data": [
    {
      "id": "org_sub_rahal_00x9",
      "name": "Rahal Industries",
      "slug": "rahal-industries",
      "subscription_status": "active",
      "plan": "growth",
      "created_at": "2026-08-25T10:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_sub_list_001",
    "timestamp": "2026-08-25T10:00:00Z",
    "cursor": null,
    "has_more": false,
    "total": 1
  }
}

2. Get one subaccount

GET /api/v1/subaccounts/{id}

{
  "data": {
    "id": "org_sub_rahal_00x9",
    "name": "Rahal Industries",
    "slug": "rahal-industries",
    "subscription_status": "active",
    "plan": "growth",
    "parent": {
      "id": "org_parent_9f2e",
      "name": "Acme HQ",
      "tenantId": "tenant_parent_9f2e",
      "relationship": "reseller"
    },
    "created_at": "2026-08-25T10:00:00Z"
  },
  "meta": { "request_id": "req_sub_get_001", "timestamp": "2026-08-25T10:00:00Z" }
}

3. List the child’s API keys

GET /api/v1/subaccounts/{id}/api-keys

{
  "data": [
    {
      "id": "key_rahal_live_01",
      "name": "Live send key",
      "key_prefix": "dv_live_sk_",
      "last_four_chars": "V4tE",
      "type": "secret",
      "scopes": ["sms:send", "sms:read"],
      "active": true,
      "lastUsedAt": "2026-08-25T09:58:00Z",
      "createdAt": "2026-08-25T10:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_sub_keys_001",
    "timestamp": "2026-08-25T10:00:00Z",
    "cursor": null,
    "has_more": false,
    "total": 1
  }
}

4. Read branding

GET /api/v1/subaccounts/{id}/branding

{
  "data": {
    "logo_url": "https://storage.googleapis.com/orbit-logos/org_sub_rahal_00x9/logo.png?sig=…",
    "logomark_url": null,
    "favicon_url": null,
    "primary_color": "#1E40AF",
    "accent_color": "#93C5FD",
    "dashboard_name": "Rahal Sales",
    "support_email": "support@rahal.example",
    "custom_domain": "hub.rahal.example",
    "inherits_from_parent": false
  },
  "meta": { "request_id": "req_sub_brand_001", "timestamp": "2026-08-25T10:00:00Z" }
}

5. List channel budgets

GET /api/v1/subaccounts/{id}/channel-budgets

The same route family reads the current set and replaces it full-set. Both shapes appear here because GET lists what the POST/PUT writes: one budget per channel.

{
  "data": {
    "subaccount_id": "org_sub_rahal_00x9",
    "budgets": [
      {
        "channel": "sms",
        "threshold_cents": 100000,
        "period": "monthly",
        "action": "block"
      }
    ]
  },
  "meta": { "request_id": "req_sub_budgets_001", "timestamp": "2026-08-25T10:00:00Z" }
}

6. List custom domains

GET /api/v1/subaccounts/{id}/domains

{
  "data": [
    {
      "id": "dom_rahal_hub_01ax",
      "organization_id": "org_sub_rahal_00x9",
      "domain": "hub.rahal.example",
      "status": "verified",
      "cname_target": "domains.orbit.devotel.io",
      "cname_verified_at": "2026-08-25T10:03:00Z",
      "ssl_cert_provisioned_at": "2026-08-25T10:05:00Z",
      "ssl_cert_secret_name": "sub-dom-01ax-tls",
      "error": null,
      "created_at": "2026-08-25T10:01:00Z",
      "updated_at": "2026-08-25T10:05:00Z"
    }
  ],
  "meta": {
    "request_id": "req_sub_doms_001",
    "timestamp": "2026-08-25T10:05:00Z",
    "cursor": null,
    "has_more": false,
    "total": 1
  }
}

7. Read the canonical CNAME target

GET /api/v1/subaccounts/{id}/domains/cname-target

{
  "data": { "cname_target": "domains.orbit.devotel.io" },
  "meta": { "request_id": "req_sub_cname_001", "timestamp": "2026-08-25T10:00:00Z" }
}

8. Download a branded invoice run

GET /api/v1/subaccounts/{id}/invoice.html

A 2xx request streams a standalone HTML document with Content-Type: text/html and Content-Disposition: attachment. Build the invoice shell from the same usage statement the JSON reads return — the wires below mirror the statement rows the HTML embeds.

{
  "data": {
    "content_type": "text/html",
    "invoice": {
      "organization_id": "org_sub_rahal_00x9",
      "period": "2026-08",
      "currency": "USD",
      "totals": {
        "quantity": 1250,
        "baseCost": 959.77,
        "markedUpPrice": 1199.09,
        "marginEarned": 239.32
      }
    }
  },
  "meta": { "request_id": "req_sub_invoice_001", "timestamp": "2026-08-25T10:02:00Z" }
}

9. Read notification sender email

GET /api/v1/subaccounts/{id}/notification-email

{
  "data": {
    "from_name": "Rahal Alerts",
    "from_address": "alerts@mail.rahal.example",
    "verified": true,
    "effective": {
      "from_address": "alerts@mail.rahal.example",
      "from_name": "Rahal Alerts",
      "source": "subaccount",
      "resolved_from_organization_id": "org_sub_rahal_00x9"
    }
  },
  "meta": { "request_id": "req_sub_notify_001", "timestamp": "2026-08-25T10:00:00Z" }
}

10. Export usage as CSV

GET /api/v1/subaccounts/{id}/usage/export.csv

One CSV attachment per call: day × channel × direction rows with quantity, base cost, marked-up price, margin earned, and a TOTAL footer. Headers: date,channel,direction,quantity,base_cost,marked_up_price,margin_earned,currency. ?period=YYYY-MM defaults to the current UTC month. The mirrored JSON below is the same figures as rows on the statement the CSV is derived from.

{
  "data": {
    "content_type": "text/csv",
    "export": {
      "organization_id": "org_sub_rahal_00x9",
      "period": "2026-08",
      "currency": "USD",
      "rows": [
        {
          "date": "2026-08-24",
          "channel": "sms",
          "direction": "outbound",
          "quantity": 1214,
          "base_cost": 930.77,
          "marked_up_price": 1163.46,
          "margin_earned": 232.69,
          "currency": "USD"
        }
      ]
    }
  },
  "meta": { "request_id": "req_sub_usage_export_001", "timestamp": "2026-08-25T10:08:00Z" }
}

11. Read live usage counters

GET /api/v1/subaccounts/{id}/usage/live

{
  "data": {
    "subaccount_id": "org_sub_rahal_00x9",
    "period": "2026-08",
    "currency": "USD",
    "channels": [
      {
        "channel": "sms",
        "spent_cents": 118492,
        "live_counter_cents": 118510,
        "breached": false,
        "budget": {
          "channel": "sms",
          "threshold_cents": 100000,
          "period": "monthly",
          "action": "block"
        }
      }
    ]
  },
  "meta": { "request_id": "req_sub_live_001", "timestamp": "2026-08-25T10:05:00Z" }
}

12. Read the usage statement JSON

GET /api/v1/subaccounts/{id}/usage/statement

{
  "data": {
    "subaccountId": "org_sub_rahal_00x9",
    "period": "2026-08",
    "marginPct": 25,
    "currency": "USD",
    "lineItems": [
      {
        "date": "2026-08-24",
        "channel": "sms",
        "direction": "outbound",
        "destination": "US",
        "quantity": 1214,
        "baseCost": 947.23,
        "currency": "USD",
        "markedUpPrice": 1184.04,
        "marginEarned": 236.81,
        "appliedMarginPct": 25
      },
      {
        "date": "2026-08-25",
        "channel": "voice",
        "direction": "outbound",
        "quantity": 36,
        "baseCost": 12.54,
        "currency": "USD",
        "markedUpPrice": 15.05,
        "marginEarned": 2.51,
        "appliedMarginPct": 20
      }
    ],
    "totals": {
      "quantity": 1250,
      "baseCost": 959.77,
      "markedUpPrice": 1199.09,
      "marginEarned": 239.32
    }
  },
  "meta": { "request_id": "req_sub_stmt_001", "timestamp": "2026-08-25T10:06:00Z" }
}

13. Meter the calling org’s BYO fee

GET /api/v1/subaccounts/byo-fee-meter

{
  "data": {
    "organization_id": "org_parent_9f2e",
    "period": "2026-08",
    "fee_cents": 4120,
    "transaction_count": 41200,
    "currency": "USD"
  },
  "meta": { "request_id": "req_sub_byo_001", "timestamp": "2026-08-25T10:00:00Z" }
}

14. List the rate-card library

GET /api/v1/subaccounts/rate-cards

{
  "data": {
    "rate_cards": [
      {
        "id": "rc_voice_us_25",
        "name": "US voice 20% + SMS US 25%",
        "lane_cells": ["voice:US:20"],
        "deck_cells": ["sms:US:25"]
      }
    ]
  },
  "meta": { "request_id": "req_sub_cards_001", "timestamp": "2026-08-25T10:07:00Z" }
}

15. Consolidated usage rollup across the tree

GET /api/v1/subaccounts/usage-rollup

{
  "data": {
    "parentOrgId": "org_parent_9f2e",
    "period": "2026-08",
    "subaccountCount": 1,
    "currency": "USD",
    "currencies": ["USD"],
    "subaccounts": [
      {
        "subaccountId": "org_sub_rahal_00x9",
        "name": "Rahal Industries",
        "slug": "rahal-industries",
        "subscription_status": "active",
        "marginPct": 25,
        "currency": "USD",
        "totals": {
          "quantity": 1250,
          "baseCost": 959.77,
          "markedUpPrice": 1199.09,
          "marginEarned": 239.32
        }
      }
    ],
    "totals": {
      "quantity": 1250,
      "baseCost": 959.77,
      "markedUpPrice": 1199.09,
      "marginEarned": 239.32
    }
  },
  "meta": { "request_id": "req_sub_rollup_001", "timestamp": "2026-08-25T10:08:00Z" }
}

16. Export the rollup as CSV

GET /api/v1/subaccounts/usage-rollup/export.csv

Same rollup as #15 streamed as one CSV attachment, one row per subaccount plus a TOTAL footer. The mirrored JSON below is the aggregated figure the CSV’s footer reads.

{
  "data": {
    "content_type": "text/csv",
    "export": {
      "parentOrgId": "org_parent_9f2e",
      "period": "2026-08",
      "subaccountCount": 1,
      "currency": "USD",
      "totals": {
        "quantity": 1250,
        "baseCost": 959.77,
        "markedUpPrice": 1199.09,
        "marginEarned": 239.32
      }
    }
  },
  "meta": { "request_id": "req_sub_rollup_export_001", "timestamp": "2026-08-25T10:08:30Z" }
}

17. Create subaccount (full envelope)

POST /api/v1/subaccounts

{
  "data": {
    "id": "org_sub_rahal_00x9",
    "name": "Rahal Industries",
    "slug": "rahal-industries",
    "plan": "growth",
    "subscription_status": "pending",
    "api_key": "dv_live_sk_9PmzRu2KqLsXfY7wBcNaV4tE",
    "created_at": "2026-08-25T10:00:00Z"
  },
  "meta": { "request_id": "req_sub_create_001", "timestamp": "2026-08-25T10:00:00Z" }
}

18. Provision a subaccount in one call

POST /api/v1/subaccounts/provision

{
  "data": {
    "parentOrgId": "org_parent_9f2e",
    "childOrgId": "org_sub_rahal_00x9",
    "subscription_status": "active",
    "pricing": {
      "reseller_margin_pct": 25,
      "monthly_spend_cap_cents": 5000000
    },
    "rate_deck": [
      { "channel": "sms", "destination": "US", "margin_pct": 25 },
      { "channel": "voice", "destination": "US", "margin_pct": 20 }
    ],
    "channel_budgets": [
      { "channel": "sms", "threshold_cents": 100000, "period": "monthly", "action": "block" }
    ]
  },
  "meta": { "request_id": "req_sub_provision_001", "timestamp": "2026-08-25T10:00:00Z" }
}

19. Update the subaccount row

PUT /api/v1/subaccounts/{id}

{
  "data": {
    "id": "org_sub_rahal_00x9",
    "name": "Rahal Industries Co.",
    "subscription_status": "active",
    "plan": "growth",
    "parent": {
      "id": "org_parent_9f2e",
      "name": "Acme HQ",
      "tenantId": "tenant_parent_9f2e",
      "relationship": "reseller"
    },
    "inherits_from_parent": false,
    "inherited_from_organization_id": null,
    "inherited_fields": null
  },
  "meta": { "request_id": "req_sub_update_001", "timestamp": "2026-08-25T10:08:30Z" }
}

20. Replace the child’s assigned rate card

PUT /api/v1/subaccounts/{id}/assigned-rate-card

{
  "data": {
    "subaccount_id": "org_sub_rahal_00x9",
    "assigned_rate_card_id": "rc_voice_us_25"
  },
  "meta": { "request_id": "req_sub_assign_001", "timestamp": "2026-08-25T10:09:00Z" }
}

21. Update branding

PUT /api/v1/subaccounts/{id}/branding

{
  "data": {
    "logo_url": "https://storage.googleapis.com/orbit-logos/org_sub_rahal_00x9/logo.png?sig=…",
    "logomark_url": null,
    "favicon_url": null,
    "primary_color": "#0B3B8F",
    "accent_color": "#93C5FD",
    "dashboard_name": "Rahal Sales",
    "support_email": "support@rahal.example",
    "custom_domain": "hub.rahal.example",
    "inherits_from_parent": false
  },
  "meta": { "request_id": "req_sub_brand_update_001", "timestamp": "2026-08-25T10:10:00Z" }
}

22. Update channel budgets

PUT /api/v1/subaccounts/{id}/channel-budgets

{
  "data": {
    "subaccount_id": "org_sub_rahal_00x9",
    "budgets": [
      {
        "channel": "sms",
        "threshold_cents": 100000,
        "period": "monthly",
        "action": "block"
      },
      {
        "channel": "voice",
        "threshold_cents": 60000,
        "period": "monthly",
        "action": "alert"
      }
    ]
  },
  "meta": { "request_id": "req_sub_budget_put_001", "timestamp": "2026-08-25T10:10:00Z" }
}

23. Update notification sender email

PUT /api/v1/subaccounts/{id}/notification-email

{
  "data": {
    "from_name": "Rahal Alerts",
    "from_address": "alerts@mail.rahal.example",
    "verified": true,
    "effective": {
      "from_address": "alerts@mail.rahal.example",
      "from_name": "Rahal Alerts",
      "source": "subaccount",
      "resolved_from_organization_id": "org_sub_rahal_00x9"
    }
  },
  "meta": { "request_id": "req_sub_notify_put_001", "timestamp": "2026-08-25T10:11:00Z" }
}

24. Create an API key for the child

POST /api/v1/subaccounts/{id}/api-keys

The response returns the plaintext key exactly once — store it before discarding the body. type: "secret" is a server-to-server key (dv_live_sk_*); type: "public" is a browser-safe key.

{
  "data": {
    "id": "key_rahal_live_02",
    "name": "Live send key",
    "key_prefix": "dv_live_sk_",
    "last_four_chars": "V4tE",
    "type": "secret",
    "scopes": ["sms:send", "sms:read"],
    "active": true,
    "lastUsedAt": null,
    "createdAt": "2026-08-25T10:02:00Z",
    "plaintextKey": "dv_live_sk_9PmzRu2KqLsXfY7wBcNaV4tE"
  },
  "meta": { "request_id": "req_sub_key_create_001", "timestamp": "2026-08-25T10:02:00Z" }
}

25. Create the channel-budget policy

POST /api/v1/subaccounts/{id}/channel-budgets

One call seeds the child’s spend-rail policy — each cell states the channel, the spend threshold, the evaluation period, and the breach action (block the next send, or alert only).

{
  "data": {
    "subaccount_id": "org_sub_rahal_00x9",
    "budgets": [
      {
        "channel": "sms",
        "threshold_cents": 100000,
        "period": "monthly",
        "action": "block"
      },
      {
        "channel": "voice",
        "threshold_cents": 60000,
        "period": "monthly",
        "action": "alert"
      }
    ]
  },
  "meta": { "request_id": "req_sub_budget_post_001", "timestamp": "2026-08-25T10:02:30Z" }
}

26. Attach a custom domain

POST /api/v1/subaccounts/{id}/domains

Returns the pending row with its CNAME target. Point the host’s DNS at cname_target, then re-check with POST /{id}/domains/{domainId}/verify until status flips to verified.

{
  "data": {
    "id": "dom_rahal_hub_01ax",
    "organization_id": "org_sub_rahal_00x9",
    "domain": "hub.rahal.example",
    "status": "pending",
    "cname_target": "domains.orbit.devotel.io",
    "cname_verified_at": null,
    "ssl_cert_provisioned_at": null
  },
  "meta": { "request_id": "req_sub_domain_post_001", "timestamp": "2026-08-25T10:03:00Z" }
}

The lifecycle at a glance

A subaccount is a child organization under your parent org. It starts pending the moment you create it, and it only becomes billing-active when you finalize. Create it, optionally attach branding and a custom domain, fund it, verify ownership of the domain, then flip it to active — and read back usage, pricing, and status. Every role gate on this page is owner or admin on the parent organization, except suspend/reactivate (owner only). Worked responses below use empty-path-safe ids, not shell echoes.

POST /subaccounts ─► POST /{id}/domains ─► POST /{id}/domains/{domainId}/verify
        │                    (optional)
        ▼
POST /{id}/transfer-credits ─► POST /{id}/finalize ─► status: active ─►
  GET /{id}/usage • GET /{id}/pricing • GET /{id}/rate-deck

Worked sequence: create → fund → finalize

1. Create the subaccount

POST /api/v1/subaccounts takes a minimal body — a name is enough; plan, limits, and reseller pricing can follow as separate calls. The response carries the new org id and the one-time plaintext default API key.

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": "Rahal Industries" }'

{
  "data": {
    "id": "org_sub_rahal_00x9",
    "name": "Rahal Industries",
    "slug": "rahal-industries",
    "plan": "starter",
    "subscription_status": "pending",
    "api_key": "dv_live_sk_9PmzRu2KqLsXfY7wBcNaV4tE",
    "created_at": "2026-08-25T10:00:00Z"
  },
  "meta": { "request_id": "req_create_001", "timestamp": "2026-08-25T10:00:00Z" }
}

Store api_key before you discard the response — it is shown once. Until finalization the subaccount is pending: reads work, but billing metering does not start.

2. Fund the wallet

Push initial credits from the parent wallet; pass a client_reference_id so a retried top-up replays instead of double-charging.

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/transfer-credits" \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 100000, "note": "Initial seed", "client_reference_id": "seed-rahal-001" }'

{
  "data": {
    "transferred": true,
    "amount_cents": 100000,
    "parent_balance_cents": 91500,
    "child_balance_cents": 100000
  },
  "meta": { "request_id": "req_transfer_001", "timestamp": "2026-08-25T10:00:30Z" }
}

3. Attach a custom domain (optional)

White-label hosts claim a domain and re-check its CNAME before finalizing.

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/domains" \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "hub.rahal.example" }'

{
  "data": {
    "id": "dom_rahal_hub_01ax",
    "organization_id": "org_sub_rahal_00x9",
    "domain": "hub.rahal.example",
    "status": "pending",
    "cname_target": "domains.orbit.devotel.io",
    "cname_verified_at": null,
    "ssl_cert_provisioned_at": null
  },
  "meta": { "request_id": "req_domain_001", "timestamp": "2026-08-25T10:01:00Z" }
}

Point the domain’s DNS at cname_target, then re-check. status flips to verified when the CNAME resolves; the SSL certificate provisions asynchronously after that.

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/domains/dom_rahal_hub_01ax/verify" \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" -d '{}'

{
  "data": {
    "id": "dom_rahal_hub_01ax",
    "status": "verified",
    "cname_verified_at": "2026-08-25T10:03:00Z"
  },
  "meta": { "request_id": "req_dverify_001", "timestamp": "2026-08-25T10:03:00Z" }
}

4. Finalize

Flip the subaccount to active. Owner or admin on the parent. The call is idempotent — a rerun on an already-active row is a 200 no-op, so a retried “Launch” click is safe.

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/finalize" \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" -d '{}'

{
  "data": { "id": "org_sub_rahal_00x9", "subscription_status": "active" },
  "meta": { "request_id": "req_finalize_001", "timestamp": "2026-08-25T10:04:00Z" }
}

Shortcut: POST /api/v1/subaccounts/provision runs create → pricing → branding → funding → finalize as one atomic call. Reach for it when onboarding is driven by your own portal instead of a human wizard.

Read back: usage, pricing, and status

Once active, the reads your reseller portal makes most:

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

{
  "data": {
    "subaccount_id": "org_sub_rahal_00x9",
    "credits_used": 118492,
    "messages_sent": 1214,
    "messages_received": 97,
    "calls_made": 36,
    "api_calls": 8120,
    "current_plan": "growth",
    "rate_limit_per_second": 20,
    "data_retention_days": 365
  },
  "meta": { "request_id": "req_usage_001", "timestamp": "2026-08-25T10:05:00Z" }
}

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

{
  "data": {
    "subaccount_id": "org_sub_rahal_00x9",
    "reseller_margin_pct": 25,
    "monthly_spend_cap_cents": 5000000,
    "current_period_spend_cents": 118492
  },
  "meta": { "request_id": "req_pricing_get_001", "timestamp": "2026-08-25T10:05:30Z" }
}

GET /{id} returns the org row (subscription_status, plan, parent hierarchy) — the status check the finalize step above flips. GET /{id}/usage/statement?period=YYYY-MM returns the billing-grade per-day × meter rows the rollup endpoint folds; GET /{id}/usage/export.csv streams the same figures as a CSV attachment to invoice your end-customer.

Rating: rate deck, rate cards, and MCCMNC overrides

Subaccount pricing is a flat reseller_margin_pct over wholesale, plus optional per-channel/destination markup cells (the rate deck) or a named rate card from the parent org’s price-book library. For specific mobile operators, layer per-MCCMNC overrides — the send-path resolver prices an SMS segment against them before falling through to the wholesale deck. Read the assigned deck — an empty rate_deck means every usage line prices at the flat margin:

curl "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/rate-deck" \
  -H "X-API-Key: dv_live_sk_your_parent_key"

{
  "data": {
    "subaccount_id": "org_sub_rahal_00x9",
    "assigned_rate_card_id": "rc_voice_us_25",
    "rate_deck": [
      { "channel": "sms", "destination": "US", "margin_pct": 25 },
      { "channel": "voice", "destination": "US", "margin_pct": 20 }
    ]
  },
  "meta": { "request_id": "req_ratedeck_001", "timestamp": "2026-08-25T10:06:00Z" }
}

List the parent org’s persisted cards — each carries at least one cell family (lane_cells and/or deck_cells); cards without cells never persist:

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

{
  "data": {
    "rate_cards": [
      {
        "id": "rc_voice_us_25",
        "name": "US voice 20% + SMS US 25%",
        "lane_cells": ["voice:US:20"],
        "deck_cells": ["sms:US:25"]
      }
    ]
  },
  "meta": { "request_id": "req_ratecards_001", "timestamp": "2026-08-25T10:06:30Z" }
}

Upsert a per-operator override — POST returns the written row; GET /{id}/mccmnc-overrides lists them cursor-paginated (meta.cursor, meta.has_more, meta.total):

curl "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/mccmnc-overrides?limit=50" \
  -H "X-API-Key: dv_live_sk_your_parent_key"

{
  "data": [
    {
      "id": "mccmncOverride_01j72k",
      "mccmnc": "52503",
      "operator_name": "SingTel Singapore",
      "country": "Singapore",
      "rate_per_unit": 0.018,
      "currency": "USD",
      "created_at": "2026-08-25T10:07:00Z"
    }
  ],
  "meta": {
    "request_id": "req_mccmnc_list_001",
    "timestamp": "2026-08-25T10:07:30Z",
    "cursor": null,
    "has_more": false,
    "total": 1
  }
}

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/mccmnc-overrides" \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{ "mccmnc": "52503", "rate_per_unit": 0.018, "currency": "USD" }'

{
  "data": {
    "id": "mccmncOverride_01j72k",
    "mccmnc": "52503",
    "operator_name": "SingTel Singapore",
    "country": "Singapore",
    "rate_per_unit": 0.018,
    "currency": "USD",
    "created_at": "2026-08-25T10:07:00Z"
  },
  "meta": { "request_id": "req_mccmnc_001", "timestamp": "2026-08-25T10:07:00Z" }
}

Subaccount ops: read back, update, and inheritance semantics

GET /api/v1/subaccounts/{id} returns the child org row with its parent hierarchy attached; PUT /api/v1/subaccounts/{id} is the PATCH-style read-modify write for the display name, plan, and white-label policy. Both are owner or admin on the parent organization. The parent block names the organization the child inherited from — inherits_from_parent: true whenever any white-label field was pulled rather than set directly. When a parent supplies a value, the org id it was pulled from appears on inherited_from_organization_id and inherited_fields maps each inherited field to that source org, exactly the resolution chain the Branding resolver documents. A child that sets its own overrides returns inherits_from_parent: false, inherited_from_organization_id: null, and inherited_fields: null.

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

{
  "data": {
    "id": "org_sub_rahal_00x9",
    "name": "Rahal Industries",
    "slug": "rahal-industries",
    "plan": "growth",
    "subscription_status": "active",
    "inherits_from_parent": true,
    "inherited_from_organization_id": "org_parent_9f2e",
    "inherited_fields": {
      "primary_color": "org_parent_9f2e",
      "accent_color": "org_parent_9f2e",
      "support_email": "org_parent_9f2e"
    },
    "parent": {
      "id": "org_parent_9f2e",
      "name": "Acme HQ",
      "tenantId": "tenant_parent_9f2e",
      "relationship": "reseller"
    },
    "created_at": "2026-08-25T10:00:00Z"
  },
  "meta": { "request_id": "req_subaccount_get_001", "timestamp": "2026-08-25T10:08:00Z" }
}

Update in place — the response echoes the merged row. An explicit null on a policy field clears the override and re-opens it to inheritance, so the parent’s value flows down on the next read:

curl -X PUT "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9" \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Rahal Industries Co.",
    "branding_policy": { "primary_color": null }
  }'

{
  "data": {
    "id": "org_sub_rahal_00x9",
    "display_name": "Rahal Industries Co.",
    "inherits_from_parent": true,
    "inherited_from_organization_id": "org_parent_9f2e",
    "inherited_fields": { "primary_color": "org_parent_9f2e" }
  },
  "meta": { "request_id": "req_subaccount_update_001", "timestamp": "2026-08-25T10:08:30Z" }
}

The hierarchy from an empty list

A brand-new parent org starts with zero children. The scaffold reads that state, creates the first subaccount, then reads it back to confirm the hierarchy is one level deep:

curl "https://api.orbit.devotel.io/api/v1/subaccounts?limit=50" \
  -H "X-API-Key: dv_live_sk_your_parent_key"

{
  "data": [],
  "meta": {
    "request_id": "req_subaccount_listempty_001",
    "timestamp": "2026-08-25T09:59:30Z",
    "cursor": null,
    "has_more": false,
    "total": 0
  }
}

Create the first child (see step 1 above), then the same list call returns one row and GET /{id} resolves the parent link — the loop your portal runs when a fresh reseller account onboards its first end-customer:

{
  "data": [
    {
      "id": "org_sub_rahal_00x9",
      "name": "Rahal Industries",
      "slug": "rahal-industries",
      "subscription_status": "pending",
      "inherits_from_parent": false,
      "inherited_from_organization_id": null,
      "inherited_fields": null
    }
  ],
  "meta": {
    "request_id": "req_subaccount_list_001",
    "timestamp": "2026-08-25T10:00:15Z",
    "cursor": null,
    "has_more": false,
    "total": 1
  }
}

Error shapes worth branching on

Every failure on this page returns the standard { "error": { "code", "message", "status" }, "meta": { "request_id", "timestamp" } } envelope. Three classes are specific to the reseller hierarchy:

Status	`error.code`	When it fires
`402`	`INSUFFICIENT_BALANCE`	A credit transfer exceeds the parent’s available wallet balance — top up the parent wallet, then retry the transfer with the same `client_reference_id`.
`409`	`CONFLICT`	A parent/hierarchy cycle: the create or update would nest the tree into a loop (for example, binding an org under its own descendant), so the hierarchy guard rejects it.
`403`	`FORBIDDEN`	The caller is not an owner or admin of the parent organization — a plain member, or a key scoped to the child, cannot manage subaccounts.
`422`	`VALIDATION_ERROR`	The parent reference is invalid: a malformed `{id}`, a parent org that does not exist, or a body field failing validation.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance to transfer 100000 cents",
    "status": 402
  },
  "meta": {
    "request_id": "req_subaccount_err_402",
    "timestamp": "2026-08-25T10:09:00Z"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "parent_organization_id must reference an existing organization",
    "status": 422
  },
  "meta": {
    "request_id": "req_subaccount_err_001",
    "timestamp": "2026-08-25T10:09:00Z"
  }
}

Treat 409 CONFLICT on a hierarchy write as terminal — retrying the same nesting replays the cycle. 402 INSUFFICIENT_BALANCE is recoverable: fund the parent, replay the transfer with the SAME client_reference_id, and the idempotent guard returns one debit, not two. 403 FORBIDDEN means your portal’s key needs elevating to the parent’s owner/admin role; 422 VALIDATION_ERROR means the request never reached the write and is safe to correct and resend.

Worked reseller provisioning chain

Use the parent organization’s API key for provisioning. The child key created in step 3 is for requests made by that subaccount; it cannot create or administer sibling subaccounts. Add X-Test-Mode: true when using Clerk session authentication against the sandbox. For API-key authentication, use a dv_test_sk_* key to enter sandbox mode; X-Test-Mode is ignored for dv_live_sk_* keys. The examples use org_child_01J8S7Q2K3M4N5P6Q7R8S9T0UV as the child id. Replace it with the id returned by step 1. Provisioning is intentionally explicit: create the pending child, finalize it, then apply credentials and controls.

1. Create the pending subaccount

Set pending_setup to true so the child stays out of the active billing state until the provisioning chain is complete. The parent key must have owner or admin access. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts" \
  -H "X-API-Key: dv_live_sk_parent_key" \
  -H "Idempotency-Key: reseller-child-acme-2026-10-12" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Support",
  "slug": "acme-support",
  "plan": "growth",
  "max_team_members": 25,
  "rate_limit_per_second": 100,
  "pending_setup": true
}'

Node.js

const parentKey = process.env.ORBIT_PARENT_API_KEY!
const baseUrl = 'https://api.orbit.devotel.io/api/v1'

const create = await fetch(`${baseUrl}/subaccounts`, {
  method: 'POST',
  headers: {
    'X-API-Key': parentKey,
    'Idempotency-Key': 'reseller-child-acme-2026-10-12',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme Support',
    slug: 'acme-support',
    plan: 'growth',
    max_team_members: 25,
    rate_limit_per_second: 100,
    pending_setup: true,
  }),
})
const created = await create.json()
const childId = created.data.id

Response

{
  "data": {
    "id": "org_child_01J8S7Q2K3M4N5P6Q7R8S9T0UV",
    "name": "Acme Support",
    "slug": "acme-support",
    "tenant_id": "tenant_01J8S7Q2K3M4N5P6Q7R8S9T0UV",
    "plan": "growth",
    "subscription_status": "pending",
    "api_key": "dv_live_sk_child_key_shown_once"
  },
  "meta": {
    "request_id": "req_subaccount_create_01",
    "timestamp": "2026-10-12T12:00:00.000Z"
  }
}

The default key is shown only when it is created. Store it securely; if it is not available, use step 3 to mint a replacement.

2. Finalize the subaccount

Finalize after the child’s required setup is ready. This idempotent call changes subscription_status from pending to active. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts/org_child_01J8S7Q2K3M4N5P6Q7R8S9T0UV/finalize" \
  -H "X-API-Key: dv_live_sk_parent_key" \
  -H "Idempotency-Key: finalize-acme-2026-10-12"

Node.js

const finalized = await fetch(`${baseUrl}/subaccounts/${childId}/finalize`, {
  method: 'POST',
  headers: {
    'X-API-Key': parentKey,
    'Idempotency-Key': 'finalize-acme-2026-10-12',
  },
})
console.log(await finalized.json())

Response

{
  "data": {
    "id": "org_child_01J8S7Q2K3M4N5P6Q7R8S9T0UV",
    "subscription_status": "active"
  },
  "meta": {
    "request_id": "req_subaccount_finalize_01",
    "timestamp": "2026-10-12T12:01:00.000Z"
  }
}

3. Create a child API key

Use the parent key to mint a child key. The plaintext key is returned once and is not recoverable from the list endpoint. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts/org_child_01J8S7Q2K3M4N5P6Q7R8S9T0UV/api-keys" \
  -H "X-API-Key: dv_live_sk_parent_key" \
  -H "Idempotency-Key: child-key-acme-2026-10-12" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme production integration",
  "type": "secret",
  "scopes": ["messages:write", "messages:read"]
}'

Node.js

const keyResponse = await fetch(`${baseUrl}/subaccounts/${childId}/api-keys`, {
  method: 'POST',
  headers: {
    'X-API-Key': parentKey,
    'Idempotency-Key': 'child-key-acme-2026-10-12',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme production integration',
    type: 'secret',
    scopes: ['messages:write', 'messages:read'],
  }),
})
const keyCreated = await keyResponse.json()
const childKey = keyCreated.data.key

Response

{
  "data": {
    "id": "key_01J8S7Q2K3M4N5P6Q7R8S9T0UV",
    "name": "Acme production integration",
    "type": "secret",
    "key": "dv_live_sk_child_key_shown_once",
    "scopes": ["messages:write", "messages:read"],
    "created_at": "2026-10-12T12:02:00.000Z"
  },
  "meta": {
    "request_id": "req_subaccount_key_01",
    "timestamp": "2026-10-12T12:02:00.000Z"
  }
}

4. Apply channel budgets

Use the parent key to manage the child’s controls. budgets is a full-set replacement: send the complete desired array, including period: "monthly" and a breach action. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts/org_child_01J8S7Q2K3M4N5P6Q7R8S9T0UV/channel-budgets" \
  -H "X-API-Key: dv_live_sk_parent_key" \
  -H "Idempotency-Key: channel-budget-acme-2026-10-12" \
  -H "Content-Type: application/json" \
  -d '{
  "budgets": [
    {"channel": "sms", "threshold_cents": 50000, "period": "monthly", "action": "throttle"},
    {"channel": "email", "threshold_cents": 25000, "period": "monthly", "action": "alert"}
  ]
}'

Node.js

const budgets = await fetch(`${baseUrl}/subaccounts/${childId}/channel-budgets`, {
  method: 'POST',
  headers: {
    'X-API-Key': parentKey,
    'Idempotency-Key': 'channel-budget-acme-2026-10-12',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    budgets: [
      { channel: 'sms', threshold_cents: 50000, period: 'monthly', action: 'throttle' },
      { channel: 'email', threshold_cents: 25000, period: 'monthly', action: 'alert' },
    ],
  }),
})
console.log(await budgets.json())

Response

{
  "data": {
    "budgets": [
      {"channel": "sms", "threshold_cents": 50000, "period": "monthly", "action": "throttle"},
      {"channel": "email", "threshold_cents": 25000, "period": "monthly", "action": "alert"}
    ]
  },
  "meta": {
    "request_id": "req_channel_budget_01",
    "timestamp": "2026-10-12T12:03:00.000Z"
  }
}

5. Read lifetime usage

Read counters from the parent key to monitor the child independently of a billing period.

cURL

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

Node.js

const lifetime = await fetch(`${baseUrl}/subaccounts/${childId}/usage`, {
  headers: { 'X-API-Key': parentKey },
})
console.log(await lifetime.json())

{
  "data": {
    "subaccount_id": "org_child_01J8S7Q2K3M4N5P6Q7R8S9T0UV",
    "credits_used": 18450,
    "messages_sent": 1260,
    "messages_received": 318,
    "calls_made": 42,
    "api_calls": 9876,
    "current_plan": "growth",
    "rate_limit_per_second": 100,
    "data_retention_days": 90
  },
  "meta": {
    "request_id": "req_lifetime_usage_01",
    "timestamp": "2026-10-12T12:04:00.000Z"
  }
}

6. Read the consolidated usage rollup

Use the parent key to retrieve the whole reseller tree for a billing period. period is YYYY-MM and defaults to the current UTC month.

cURL

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

Node.js

const rollup = await fetch(`${baseUrl}/subaccounts/usage-rollup?period=2026-10`, {
  headers: { 'X-API-Key': parentKey },
})
console.log(await rollup.json())

{
  "data": {
    "parentOrgId": "org_parent_01J8S7Q2K3M4N5P6Q7R8S9T0UV",
    "period": "2026-10",
    "subaccountCount": 1,
    "currency": "USD",
    "currencies": ["USD"],
    "subaccounts": [{
      "subaccountId": "org_child_01J8S7Q2K3M4N5P6Q7R8S9T0UV",
      "name": "Acme Support",
      "slug": "acme-support",
      "status": "active",
      "marginPct": 12.5,
      "currency": "USD",
      "totals": {"quantity": 1578, "baseCost": 18.42, "markedUpPrice": 20.72, "marginEarned": 2.30}
    }],
    "totals": {"quantity": 1578, "baseCost": 18.42, "markedUpPrice": 20.72, "marginEarned": 2.30}
  },
  "meta": {
    "request_id": "req_usage_rollup_01",
    "timestamp": "2026-10-12T12:05:00.000Z"
  }
}

7. Suspend and reactivate the child

Both lifecycle operations use the parent key and return the resulting state. Suspending stops send activity without deleting the child; reactivation restores active status. Both calls are idempotent.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts/org_child_01J8S7Q2K3M4N5P6Q7R8S9T0UV/suspend" \
  -H "X-API-Key: dv_live_sk_parent_key"

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts/org_child_01J8S7Q2K3M4N5P6Q7R8S9T0UV/reactivate" \
  -H "X-API-Key: dv_live_sk_parent_key"

Node.js

for (const action of ['suspend', 'reactivate'] as const) {
  const state = await fetch(`${baseUrl}/subaccounts/${childId}/${action}`, {
    method: 'POST',
    headers: { 'X-API-Key': parentKey },
  })
  console.log(action, await state.json())
}

Suspend response

{
  "data": {"id": "org_child_01J8S7Q2K3M4N5P6Q7R8S9T0UV", "status": "suspended"},
  "meta": {"request_id": "req_suspend_01", "timestamp": "2026-10-12T12:06:00.000Z"}
}

Reactivate response

{
  "data": {"id": "org_child_01J8S7Q2K3M4N5P6Q7R8S9T0UV", "status": "active"},
  "meta": {"request_id": "req_reactivate_01", "timestamp": "2026-10-12T12:07:00.000Z"}
}

The same parent-key distinction applies to the reseller controls around this chain. Use POST /api/v1/subaccounts/{id}/mccmnc-overrides for an operator-specific sell rate, PUT /api/v1/subaccounts/{id}/rate-deck for differentiated channel pricing, POST /api/v1/subaccounts/{id}/domains followed by POST /api/v1/subaccounts/{id}/domains/{domainId}/verify for custom domains, and GET /api/v1/subaccounts/{id}/invoice.html for an invoice export. These endpoints return the configured tenant-owned controls; they do not change provider routing.

Worked recipes

The recipes below survive regeneration: they are mirrored here in api-reference/endpoints/_overlay/subaccounts.mdx and re-spliced by the doc generator. Do not hand-edit the generated operation sections; correct samples in this overlay and regenerate.

Three end-to-end sequences that cover a reseller’s first week on the API: onboard a subaccount and mint its keys, white-label its dashboard, and run the billing loop. Responses below are full envelopes, identical in shape to what the operations above return.

Recipe 1: Create and provision a subaccount

Create the child org, read it back once it is active, then mint the key its integration will use.

cURL

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": "Rahal Industries",
    "contact_email": "ops@rahal.example",
    "capabilities": ["sms", "voice"]
  }'

Node.js

const created = await orbit.request('POST', '/subaccounts', {
  body: { name: 'Rahal Industries', contact_email: 'ops@rahal.example', capabilities: ['sms', 'voice'] },
})
// created.data.api_key is the child's default key — shown once, store it now.

{
  "data": {
    "id": "org_sub_rahal_00x9",
    "name": "Rahal Industries",
    "slug": "rahal-industries",
    "contact_email": "ops@rahal.example",
    "capabilities": ["sms", "voice"],
    "subscription_status": "pending",
    "api_key": "dv_live_sk_9PmzRu2KqLsXfY7wBcNaV4tE",
    "created_at": "2026-10-15T09:00:00Z"
  },
  "meta": { "request_id": "req_recipe_create_001", "timestamp": "2026-10-15T09:00:00Z" }
}

The subaccount starts pending. Finalize it (or let your provisioning flow call POST /api/v1/subaccounts/provision) and the same read now reports active:

cURL

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

Node.js

const child = await orbit.request('GET', `/subaccounts/${childId}`)
// subscription_status flips pending -> active once the child is finalized.

{
  "data": {
    "id": "org_sub_rahal_00x9",
    "name": "Rahal Industries",
    "slug": "rahal-industries",
    "contact_email": "ops@rahal.example",
    "capabilities": ["sms", "voice"],
    "subscription_status": "active",
    "parent": {
      "id": "org_parent_9f2e",
      "name": "Acme HQ",
      "relationship": "reseller"
    },
    "created_at": "2026-10-15T09:00:00Z"
  },
  "meta": { "request_id": "req_recipe_get_001", "timestamp": "2026-10-15T09:05:00Z" }
}

Mint a scoped key for the child’s integration. The plaintext key is returned exactly once; the list endpoint only ever shows the prefix and last four characters.

cURL

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

Node.js

const key = await orbit.request('POST', `/subaccounts/${childId}/api-keys`, {
  body: { name: 'Rahal production', type: 'secret', scopes: ['messages:write', 'messages:read'] },
})
// key.data.key is the plaintext dv_sk_sub_… secret — store it now, it is shown once.

{
  "data": {
    "id": "key_rahal_live_02",
    "name": "Rahal production",
    "type": "secret",
    "key": "dv_sk_sub_9PmzRu2KqLsXfY7wBcNaV4tE",
    "key_prefix": "dv_sk_sub_",
    "last_four_chars": "V4tE",
    "scopes": ["messages:write", "messages:read"],
    "created_at": "2026-10-15T09:06:00Z"
  },
  "meta": { "request_id": "req_recipe_key_001", "timestamp": "2026-10-15T09:06:00Z" }
}

Recipe 2: White-label a subaccount

Set the child’s branding, read it back normalized, then verify the custom domain the branded dashboard is served from.

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/branding" \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{
    "logo_url": "https://cdn.rahal.example/logo.png",
    "primary_color": "#1e40af",
    "dashboard_name": "Rahal Sales"
  }'

Node.js

const branding = await orbit.request('PUT', `/subaccounts/${childId}/branding`, {
  body: { logo_url: 'https://cdn.rahal.example/logo.png', primary_color: '#1e40af', dashboard_name: 'Rahal Sales' },
})
// colors come back uppercase-normalized; unset fields resolve from the parent org.

{
  "data": {
    "logo_url": "https://cdn.rahal.example/logo.png",
    "logomark_url": null,
    "favicon_url": null,
    "primary_color": "#1E40AF",
    "accent_color": "#3B82F6",
    "dashboard_name": "Rahal Sales",
    "support_email": "support@rahal.example",
    "custom_domain": "hub.rahal.example",
    "inherits_from_parent": false
  },
  "meta": { "request_id": "req_recipe_brand_001", "timestamp": "2026-10-15T09:10:00Z" }
}

GET branding returns the same row with inherited values folded in: anything you did not set resolves from the parent org and flips inherits_from_parent to true for those fields. Colors come back uppercase-normalized. Attach the custom domain and read the CNAME target it must point at:

cURL

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

curl "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/domains/cname-target" \
  -H "X-API-Key: dv_live_sk_your_parent_key"

Node.js

const domains = await orbit.request('GET', `/subaccounts/${childId}/domains`)
const cname = await orbit.request('GET', `/subaccounts/${childId}/domains/cname-target`)
// point each claimed domain's CNAME at cname.data.cname_target, then verify.

{
  "data": [
    {
      "id": "dom_rahal_hub_01ax",
      "organization_id": "org_sub_rahal_00x9",
      "domain": "hub.rahal.example",
      "status": "pending",
      "cname_target": "domains.orbit.devotel.io",
      "cname_verified_at": null,
      "ssl_cert_provisioned_at": null,
      "created_at": "2026-10-15T09:12:00Z"
    }
  ],
  "meta": {
    "request_id": "req_recipe_domains_001",
    "timestamp": "2026-10-15T09:12:00Z",
    "cursor": null,
    "has_more": false,
    "total": 1
  }
}

{
  "data": { "cname_target": "domains.orbit.devotel.io" },
  "meta": { "request_id": "req_recipe_cname_001", "timestamp": "2026-10-15T09:12:30Z" }
}

Add a CNAME record for hub.rahal.example pointing at domains.orbit.devotel.io, then re-check with POST /api/v1/subaccounts/{id}/domains/{domainId}/verify. When status flips to verified, the SSL certificate provisions within a few minutes.

Recipe 3: The reseller billing loop

Cap what the child can spend, read back the tier pricing you set, and pull the branded invoice.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/channel-budgets" \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{
    "budgets": [
      { "channel": "sms", "threshold_cents": 100000, "period": "monthly", "action": "block" }
    ]
  }'

Node.js

const budgets = await orbit.request('POST', `/subaccounts/${childId}/channel-budgets`, {
  body: { budgets: [{ channel: 'sms', threshold_cents: 100000, period: 'monthly', action: 'block' }] },
})

Python

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request(
    "POST",
    "/subaccounts/org_sub_rahal_00x9/channel-budgets",
    {
        "budgets": [
            {"channel": "sms", "threshold_cents": 100000, "period": "monthly", "action": "block"}
        ]
    },
)

budgets := map[string]any{
	"budgets": []map[string]any{
		{"channel": "sms", "threshold_cents": 100000, "period": "monthly", "action": "block"},
	},
}

var written map[string]any
if err := client.Request(context.Background(), "POST", "/api/v1/subaccounts/org_sub_rahal_00x9/channel-budgets", nil, budgets, &written, ""); err != nil {
	panic(err)
}

Ruby

res = client.request("POST", "/subaccounts/org_sub_rahal_00x9/channel-budgets", json_body: {
  budgets: [
    { channel: "sms", threshold_cents: 100_000, period: "monthly", action: "block" },
  ],
})

PHP

$res = $client->request(
    method: "POST",
    path: "/subaccounts/org_sub_rahal_00x9/channel-budgets",
    jsonBody: [
        "budgets" => [
            ["channel" => "sms", "threshold_cents" => 100000, "period" => "monthly", "action" => "block"],
        ],
    ],
);

{
  "data": {
    "subaccount_id": "org_sub_rahal_00x9",
    "budgets": [
      { "channel": "sms", "threshold_cents": 100000, "period": "monthly", "action": "block" }
    ]
  },
  "meta": { "request_id": "req_recipe_budget_001", "timestamp": "2026-10-15T09:20:00Z" }
}

threshold_cents is the monthly spend cap for the channel; action: "block" hard-stops sends at the cap, "alert" keeps sending and notifies you. GET reseller pricing returns the margin tiers applied to the child’s usage:

cURL

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

Node.js

const pricing = await orbit.request('GET', `/subaccounts/${childId}/pricing`)

Python

res = client.request("GET", "/subaccounts/org_sub_rahal_00x9/pricing")

var pricing map[string]any
if err := client.Request(context.Background(), "GET", "/api/v1/subaccounts/org_sub_rahal_00x9/pricing", nil, nil, &pricing, ""); err != nil {
	panic(err)
}

Ruby

res = client.request("GET", "/subaccounts/org_sub_rahal_00x9/pricing")

PHP

$res = $client->request(method: "GET", path: "/subaccounts/org_sub_rahal_00x9/pricing");

{
  "data": {
    "subaccount_id": "org_sub_rahal_00x9",
    "reseller_margin_pct": 25,
    "monthly_spend_cap_cents": 5000000,
    "current_period_spend_cents": 118492,
    "tiers": [
      { "channel": "sms", "destination": "US", "margin_pct": 25 },
      { "channel": "voice", "destination": "US", "margin_pct": 20 }
    ]
  },
  "meta": { "request_id": "req_recipe_pricing_001", "timestamp": "2026-10-15T09:21:00Z" }
}

GET invoice.html does not return JSON: it streams a standalone HTML document, so save it to a file. The response carries Content-Type: text/html; charset=utf-8 and Content-Disposition: attachment; filename="invoice-<period>.html".

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

import { writeFileSync } from 'node:fs'

const invoice = await fetch(
  'https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/invoice.html?period=2026-09',
  { headers: { 'X-API-Key': process.env.ORBIT_API_KEY! } },
)
if (!invoice.ok) throw new Error(`Invoice download failed: ${invoice.status}`)
writeFileSync('invoice.html', Buffer.from(await invoice.arrayBuffer()))

import os, requests

r = requests.get(
    "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/invoice.html",
    params={"period": "2026-09"},
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
r.raise_for_status()
with open("invoice.html", "wb") as fh:
    fh.write(r.content)

req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/invoice.html?period=2026-09", nil)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
body, _ := io.ReadAll(res.Body)
os.WriteFile("invoice.html", body, 0o644)

require 'net/http'

res = Net::HTTP.get_response(URI('https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/invoice.html?period=2026-09'))
res.value # raise on 4xx/5xx
File.write('invoice.html', res.body)

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/invoice.html?period=2026-09');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
file_put_contents('invoice.html', curl_exec($ch));

Open invoice.html in a browser: it is the branded statement for the period, with per-day line items and totals, ready to forward to your end-customer.

Suspended subaccounts

Writes against a suspended subaccount return 403 with a dedicated code so your portal can distinguish “paused by the reseller” from “missing permission”:

Status	`error.code`	When it fires
`403`	`subaccount_suspended`	The subaccount is suspended; sends and writes are rejected until `POST /{id}/reactivate` restores `active`.

{
  "error": {
    "code": "subaccount_suspended",
    "message": "Subaccount org_sub_rahal_00x9 is suspended; reactivate it to resume sending.",
    "status": 403
  },
  "meta": { "request_id": "req_recipe_err_403", "timestamp": "2026-10-15T09:30:00Z" }
}

Reseller orientation and the worked chain

27. Reseller orientation: subaccount vs tenant

Your organization is one tenant; a subaccount is a child organization provisioned under it, with its own id (org_sub_*), its own API keys, branding, and spend caps. Billing rolls up to you, the reseller parent: the child’s usage is marked up at your margin and folded into your statement, while the child sees only its own traffic. You administer children with your parent key; the child’s keys act only on the child, so an end-customer integration can never touch your organization or its other subaccounts. A subaccount inherits your defaults (rate card, notification sender, compliance settings) until you override them per child. Treat the child id the create call returns as the handle for everything that follows: key minting, usage, budgets, and suspension all take {id}.

28. Worked chain: create, mint a scoped key, send, read back usage

Run these four round trips in order to take a new end-customer from provisioning to live traffic. Substitute your own ids and keep the child key from round trip 2; it is shown once. Round trip 1 — Create the subaccount

POST /api/v1/subaccounts

cURL

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": "Rahal Industries",
  "billing_email": "billing@rahal.example",
  "monthly_spend_cap_cents": 5000000
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/subaccounts', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Rahal Industries",
    "billing_email": "billing@rahal.example",
    "monthly_spend_cap_cents": 5000000
  }),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/subaccounts", headers=headers, json={
  "name": "Rahal Industries",
  "billing_email": "billing@rahal.example",
  "monthly_spend_cap_cents": 5000000
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/subaccounts", bytes.NewBuffer([]byte(`{
  "name": "Rahal Industries",
  "billing_email": "billing@rahal.example",
  "monthly_spend_cap_cents": 5000000
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/subaccounts')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "name": "Rahal Industries",
  "billing_email": "billing@rahal.example",
  "monthly_spend_cap_cents": 5000000
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/subaccounts');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "name": "Rahal Industries",
  "billing_email": "billing@rahal.example",
  "monthly_spend_cap_cents": 5000000
}
JSON);
echo curl_exec($ch);

The child id in data.id is the {id} every later step takes. billing_email receives the child’s invoices; monthly_spend_cap_cents hard-stops the child’s send traffic at the cap.

{
  "data": {
    "id": "org_sub_rahal_00x9",
    "name": "Rahal Industries",
    "slug": "rahal-industries",
    "plan": "growth",
    "subscription_status": "pending",
    "created_at": "2026-08-25T10:00:00Z"
  },
  "meta": { "request_id": "req_chain_create_001", "timestamp": "2026-08-25T10:00:00Z" }
}

subscription_status starts pending and flips to active once the child is finalized (step 4 of the lifecycle above). The samples below assume a finalized child. Round trip 2 — Mint a scoped API key for the child

POST /api/v1/subaccounts/{id}/api-keys

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/api-keys" \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Rahal live send key",
  "type": "secret",
  "scopes": ["sms:send", "sms:read"]
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/api-keys', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Rahal live send key",
    "type": "secret",
    "scopes": ["sms:send", "sms:read"]
  }),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/api-keys", headers=headers, json={
  "name": "Rahal live send key",
  "type": "secret",
  "scopes": ["sms:send", "sms:read"]
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/api-keys", bytes.NewBuffer([]byte(`{
  "name": "Rahal live send key",
  "type": "secret",
  "scopes": ["sms:send", "sms:read"]
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/api-keys')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "name": "Rahal live send key",
  "type": "secret",
  "scopes": ["sms:send", "sms:read"]
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/api-keys');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "name": "Rahal live send key",
  "type": "secret",
  "scopes": ["sms:send", "sms:read"]
}
JSON);
echo curl_exec($ch);

Hand the child’s integration plaintextKey and nothing else: it is scoped to this subaccount and to the scopes you listed, and it is returned exactly once.

{
  "data": {
    "id": "key_rahal_live_02",
    "name": "Rahal live send key",
    "key_prefix": "dv_live_sk_",
    "last_four_chars": "V4tE",
    "type": "secret",
    "scopes": ["sms:send", "sms:read"],
    "active": true,
    "lastUsedAt": null,
    "createdAt": "2026-08-25T10:02:00Z",
    "plaintextKey": "dv_live_sk_9PmzRu2KqLsXfY7wBcNaV4tE"
  },
  "meta": { "request_id": "req_chain_key_001", "timestamp": "2026-08-25T10:02:00Z" }
}

Round trip 3 — Send on the child’s behalf The child’s integration now calls the regular send endpoints with its own key in the X-API-Key header; no parent credential and no extra parameter are needed. The response meta names the subaccount the send was billed to.

POST /api/v1/messages/sms

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/sms" \
  -H "X-API-Key: dv_live_sk_9PmzRu2KqLsXfY7wBcNaV4tE" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+14155550142",
  "from": "+14155550100",
  "message": "Your order 4821 ships today; tracking follows."
}'

Node.js

// The child key goes in X-API-Key; nothing else marks the request as subaccount traffic.
const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/sms', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.RAHAL_CHILD_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "to": "+14155550142",
    "from": "+14155550100",
    "message": "Your order 4821 ships today; tracking follows."
  }),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["RAHAL_CHILD_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/messages/sms", headers=headers, json={
  "to": "+14155550142",
  "from": "+14155550100",
  "message": "Your order 4821 ships today; tracking follows."
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/sms", bytes.NewBuffer([]byte(`{
  "to": "+14155550142",
  "from": "+14155550100",
  "message": "Your order 4821 ships today; tracking follows."
}`)))
	req.Header.Set("X-API-Key", os.Getenv("RAHAL_CHILD_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/sms')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['RAHAL_CHILD_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "to": "+14155550142",
  "from": "+14155550100",
  "message": "Your order 4821 ships today; tracking follows."
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/sms');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('RAHAL_CHILD_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "to": "+14155550142",
  "from": "+14155550100",
  "message": "Your order 4821 ships today; tracking follows."
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "msg_chain_7f3a91c2",
    "channel": "sms",
    "to": "+14155550142",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_chain_send_001",
    "timestamp": "2026-08-25T10:05:00Z",
    "subaccount_id": "org_sub_rahal_00x9"
  }
}

meta.subaccount_id echoes the child the key belongs to; the same id appears on the usage rows in round trip 4, so reconciliation ties sends to the child without extra bookkeeping. Round trip 4 — Read back per-subaccount usage Call with your parent key to audit one child’s spend for a period; the child’s own key sees the same rows for itself.

GET /api/v1/subaccounts/{id}/usage

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/usage?period=2026-10', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/usage", headers=headers, params={"period": "2026-10"})
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/usage?period=2026-10", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/usage?period=2026-10')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/usage?period=2026-10');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

{
  "data": {
    "subaccount_id": "org_sub_rahal_00x9",
    "period": "2026-10",
    "channels": [
      { "channel": "sms", "delivered": 1284, "cost_cents": 9865 },
      { "channel": "voice", "minutes": 341.6, "cost_cents": 4102 }
    ]
  },
  "meta": {
    "request_id": "req_chain_usage_001",
    "timestamp": "2026-08-25T10:06:00Z",
    "cursor": "cur_usage_rahal_0002",
    "has_more": true,
    "total": 4
  }
}

Page with meta.cursor until has_more is false; total counts the rows for the period. For the margin math on the same rows, use GET /api/v1/subaccounts/{id}/usage/statement (sample 12 above).

29. Suspend and reactivate

Suspend halts a child’s send traffic without deleting its data; billing ownership stays with you. Reactivate is the inverse and is a no-op on an already-active child, so retries are safe.

POST /api/v1/subaccounts/{id}/suspend

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/suspend" \
  -H "X-API-Key: dv_live_sk_your_parent_key"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/subaccounts/org_sub_rahal_00x9/suspend', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
console.log(await res.json())

{
  "data": {
    "id": "org_sub_rahal_00x9",
    "status": "suspended"
  },
  "meta": { "request_id": "req_chain_suspend_001", "timestamp": "2026-08-25T10:40:00Z" }
}

While suspended, the child’s integrations keep authenticating but every send and write is rejected with 403 subaccount_suspended, so a portal can tell “paused by the reseller” apart from a bad key:

{
  "error": {
    "code": "subaccount_suspended",
    "message": "Subaccount org_sub_rahal_00x9 is suspended; reactivate it to resume sending.",
    "status": 403
  },
  "meta": { "request_id": "req_chain_err_403", "timestamp": "2026-08-25T10:41:00Z" }
}

Restore the child with POST /api/v1/subaccounts/org_sub_rahal_00x9/reactivate; the response mirrors the suspend shape with "status": "active".

30. SDKs without typed subaccount helpers

No SDK ships typed methods for the subaccount routes yet, so the typed tabs on this page use plain fetch against the same paths. In Python, Go, Ruby, and PHP use the client’s generic request escape hatch instead; it signs the request exactly like the typed helpers and returns the same { data, meta } envelope.

cURL

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": "Rahal Industries", "billing_email": "billing@rahal.example", "monthly_spend_cap_cents": 5000000 }'

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/subaccounts', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ "name": "Rahal Industries", "billing_email": "billing@rahal.example", "monthly_spend_cap_cents": 5000000 }),
})
console.log(await res.json())

Python

import os
from orbit import OrbitClient

client = OrbitClient(api_key=os.environ["ORBIT_API_KEY"])
res = client.request("POST", "/api/v1/subaccounts", json={
  "name": "Rahal Industries",
  "billing_email": "billing@rahal.example",
  "monthly_spend_cap_cents": 5000000
})
print(res.json())

// Generic escape hatch until typed subaccount helpers ship.
var created map[string]any
err := client.request(ctx, "POST", "/api/v1/subaccounts", payload, &created)

Ruby

res = client.request(:post, "/api/v1/subaccounts", body: {
  name: "Rahal Industries",
  billing_email: "billing@rahal.example",
  monthly_spend_cap_cents: 5_000_000
})
puts res.body

PHP

<?php
$res = $client->request('POST', '/api/v1/subaccounts', [
    'json' => [
        'name' => 'Rahal Industries',
        'billing_email' => 'billing@rahal.example',
        'monthly_spend_cap_cents' => 5000000,
    ],
]);
echo (string) $res->getBody();

​Real envelopes for the generated { data: {} } shells

​1. List subaccounts

​2. Get one subaccount

​3. List the child’s API keys

​4. Read branding

​5. List channel budgets

​6. List custom domains

​7. Read the canonical CNAME target

​8. Download a branded invoice run

​9. Read notification sender email

​10. Export usage as CSV

​11. Read live usage counters

​12. Read the usage statement JSON

​13. Meter the calling org’s BYO fee

​14. List the rate-card library

​15. Consolidated usage rollup across the tree

​16. Export the rollup as CSV

​17. Create subaccount (full envelope)

​18. Provision a subaccount in one call

​19. Update the subaccount row

​20. Replace the child’s assigned rate card

​21. Update branding

​22. Update channel budgets

​23. Update notification sender email

​24. Create an API key for the child

​25. Create the channel-budget policy

​26. Attach a custom domain

​The lifecycle at a glance

​Worked sequence: create → fund → finalize

​1. Create the subaccount

​2. Fund the wallet

​3. Attach a custom domain (optional)

​4. Finalize

​Read back: usage, pricing, and status

​Rating: rate deck, rate cards, and MCCMNC overrides

​Subaccount ops: read back, update, and inheritance semantics

​The hierarchy from an empty list

​Error shapes worth branching on

​Worked reseller provisioning chain

​1. Create the pending subaccount

​2. Finalize the subaccount

​3. Create a child API key

​4. Apply channel budgets

​5. Read lifetime usage

​6. Read the consolidated usage rollup

​7. Suspend and reactivate the child

​Worked recipes

​Recipe 1: Create and provision a subaccount

​Recipe 2: White-label a subaccount

​Recipe 3: The reseller billing loop

​Suspended subaccounts

​Reseller orientation and the worked chain

​27. Reseller orientation: subaccount vs tenant

​28. Worked chain: create, mint a scoped key, send, read back usage

​29. Suspend and reactivate

​30. SDKs without typed subaccount helpers

Real envelopes for the generated `{ data: {} }` shells

1. List subaccounts

2. Get one subaccount

3. List the child’s API keys

4. Read branding

5. List channel budgets

6. List custom domains

7. Read the canonical CNAME target

8. Download a branded invoice run

9. Read notification sender email

10. Export usage as CSV

11. Read live usage counters

12. Read the usage statement JSON

13. Meter the calling org’s BYO fee

14. List the rate-card library

15. Consolidated usage rollup across the tree

16. Export the rollup as CSV

17. Create subaccount (full envelope)

18. Provision a subaccount in one call

19. Update the subaccount row

20. Replace the child’s assigned rate card

21. Update branding

22. Update channel budgets

23. Update notification sender email

24. Create an API key for the child

25. Create the channel-budget policy

26. Attach a custom domain

The lifecycle at a glance

Worked sequence: create → fund → finalize

1. Create the subaccount

2. Fund the wallet

3. Attach a custom domain (optional)

4. Finalize

Read back: usage, pricing, and status

Rating: rate deck, rate cards, and MCCMNC overrides

Subaccount ops: read back, update, and inheritance semantics

The hierarchy from an empty list

Error shapes worth branching on

Worked reseller provisioning chain

1. Create the pending subaccount

2. Finalize the subaccount

3. Create a child API key

4. Apply channel budgets

5. Read lifetime usage

6. Read the consolidated usage rollup

7. Suspend and reactivate the child

Worked recipes

Recipe 1: Create and provision a subaccount

Recipe 2: White-label a subaccount

Recipe 3: The reseller billing loop

Suspended subaccounts

Reseller orientation and the worked chain

27. Reseller orientation: subaccount vs tenant

28. Worked chain: create, mint a scoped key, send, read back usage

29. Suspend and reactivate

30. SDKs without typed subaccount helpers