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

# New subaccount wizard: a step-by-step walkthrough

> Walk through the dashboard's guided New subaccount flow — Basics, Brand, Domain, Connections, Credits, Review — plus the API calls each step issues, failure paths, and how to verify the result.

# New subaccount wizard: step-by-step

The dashboard ships a guided flow at **Settings → Subaccounts → New subaccount** (`/settings/subaccounts/new`) that provisions a child organization step by step instead of in one API call. Reach for it when a human approves each stage — brand assets, a custom domain, funding — before the subaccount goes live. Automation that onboards customers from your own portal should use the one-call [`POST /api/v1/subaccounts/provision`](/guides/subaccounts-reseller) instead.

The walkthrough below names the exact API call each step issues, so you can trace every screen to its endpoint. Every call runs under a parent-org session with the **owner** or **admin** role; the initial credit transfer is owner-only.

<Note>
  The wizard persists your in-progress draft in the browser, so closing the tab or coming back tomorrow resumes where you left off. A saved API key is shown once in memory and never written to the draft.
</Note>

## Step 1 — Basics

Creates the subaccount and decides its tenant-level limits.

| Field | What it sets |
| - | - |
| **Organization name** | Display name; the slug below auto-derives from it until you edit the slug yourself |
| **Slug** | Lowercase letters, digits, hyphens — used in URLs and API responses |
| **Max team members** | Seat cap for the child organization (1–500) |
| **Rate limit (req/s)** | Sustained API rate limit for the child (1–10,000); the step shows the effective req/s + req/min equivalent before you commit |

Continuing issues:

```
POST /api/v1/subaccounts
{
  "name": "Acme Retail",
  "max_team_members": 10,
  "rate_limit_per_second": 1000,
  "pending_setup": true
}
```

On success the API returns `201` with the new subaccount `id`, `tenant_id`, `slug`, and a one-time `api_key`. Save the key when it is shown — it cannot be retrieved later, only rotated. `pending_setup: true` leaves the subaccount in `pending` status so an abandoned setup never leaves a billing-active tenant behind; the final step flips it to `active`.

The create is idempotent: the wizard sends a stable `Idempotency-Key` per registration, so a retry after a lost response replays the first attempt instead of colliding on the slug with a `409`.

## Step 2 — Brand

Decides how the subaccount's dashboard looks to its users.

* **Inherit branding from parent** (default) — the child renders with your logo, colours, and dashboard name. Nothing else to fill in.
* **Custom branding** — turn inheritance off and supply a dashboard name, a logo, a favicon, and at least one brand colour (primary or accent). Logo and favicon accept PNG, JPEG, WebP, or GIF up to 2 MB.

Continuing issues `PUT /api/v1/subaccounts/{id}/branding` — either `{ "inherit_from_parent": true }` or the override fields (`dashboard_name`, `logo_url`, `favicon_url`, `primary_color`, `accent_color`).

## Step 3 — Domain (optional)

Serves the subaccount's dashboard from its own hostname with an automatically provisioned SSL certificate. Skippable — you can add a domain later from the subaccount's detail page.

1. At your DNS provider, add a **CNAME** record for the hostname pointing at the target the step displays.
2. Enter the hostname and click **Register** — issues `POST /api/v1/subaccounts/{id}/domains`.
3. Click **Verify** — issues `POST /api/v1/subaccounts/{id}/domains/{domainId}/verify`. The status chip moves through `pending` → `verifying` (CNAME matched, certificate provisioning) → `active`. A background verifier also flips the status without another click once DNS propagates.

Verification failures surface a plain-language error — a CNAME pointing at the wrong target or a DNS lookup failure — rather than the raw provider string.

## Step 4 — Connections (optional)

Per-channel decision: whether your subaccounts send on the platform's shared connection or on a connection **you** bring (your own SIP trunk, SMPP account, email domain, WhatsApp Business account, and so on). The toggle is per channel and applies to every subaccount — there is no per-subaccount override. Skippable; subaccounts run on the platform default until you set a BYO connection.

The full model, provider types, and billing shape are in [Per-channel connection mode](/guides/subaccount-connection-modes).

## Step 5 — Credits

Sets the subaccount's pricing and optionally funds it.

| Field | What it sets |
| - | - |
| **Reseller margin (%)** | Flat markup over wholesale, 0–100 |
| **Monthly spend cap** | Optional ceiling so one subaccount cannot draw the parent wallet past its budget |
| **Initial credit transfer** | Optional one-time funding push from the parent wallet — shown to owners only |

Continuing issues `PUT /api/v1/subaccounts/{id}/pricing` with `reseller_margin_pct` and `monthly_spend_cap_cents`, then — if a non-zero transfer was entered and you are an owner — `POST /api/v1/subaccounts/{id}/transfer-credits`. The step shows your current parent balance and blocks a transfer that would exceed it. Pricing saves even when the transfer is skipped, so an admin can finish the wizard and have an owner fund the subaccount later.

## Step 6 — Review & launch

Read-back of everything the flow captured: name and slug, seat and rate limits, branding mode, registered domain and its verification status, margin, spend cap, and the initial transfer.

**Launch subaccount** issues `POST /api/v1/subaccounts/{id}/finalize`, flipping the subaccount from `pending` to `active`. The endpoint is idempotent — a retried launch after a network blip returns success and changes nothing — and lands you on the new subaccount's detail page.

## Degraded-failure paths

* **A failed step keeps its state.** The step surfaces an inline error and stays put; nothing submitted earlier is lost, and the draft persists in the browser.
* **Create times out or drops mid-flight.** Provisioning builds the child's tenant synchronously and can take most of a minute. Retrying continues with the same idempotency key, so you converge on the first attempt's `201` — you never create a duplicate or fight a `409` slug loop.
* **Insufficient balance on the transfer.** The step reports that the parent wallet cannot cover the amount. Pricing was already saved; lower the amount or fund the parent and retry.
* **Owner-only transfer as an admin.** The transfer input is hidden for non-owners; if it still fires, the step explains that only owners can move credits and that pricing is already saved — an owner can fund the subaccount later from its billing page.
* **Domain verification fails.** The status chip shows `failed` with a plain-language reason. Fix the CNAME, click **Verify** again, or skip the step and add the domain later.
* **Resuming a deleted registration.** If the pending subaccount your draft points at was deleted from the subaccounts list, the wizard detects the dead pointer on load, discards the stale draft, and starts you on a clean step 1.
* **Starting over.** "Start a new registration" asks for confirmation, deletes the pending subaccount created at step 1 if one exists, and resets to a blank step 1 — so no half-configured `pending` row is orphaned.
* **Pending forever.** A subaccount abandoned in `pending` shows in your list but cannot serve traffic. Finalize it (idempotent, safe to retry) or delete it — see [White-label subaccounts](/guides/subaccounts-reseller).

## Verify the result

* **Dashboard** — the subaccount appears under **Settings → Subaccounts** with status `active` and its domain verification state.
* **API** — `GET /api/v1/subaccounts/{id}` returns the subaccount with its limits and pricing; `GET /api/v1/subaccounts` lists it among your children.
* **Audit log** — the parent's **Settings → Audit log** records the create and the finalize, so you can confirm who launched the subaccount and when.

## See also

* [White-label subaccounts](/guides/subaccounts-reseller) — the reseller surface: one-call provisioning, funding, margins, suspend/reactivate, and retirement
* [Per-channel connection mode](/guides/subaccount-connection-modes) — BYO vs platform default per channel, inherited by every subaccount
* [Per-subaccount AI configuration](/guides/subaccount-ai-configuration) — enable/disable, provider pin, and comped marker per child
* [Subaccounts API](/api-reference/subaccounts) — full endpoint catalog


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