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

# Create account

> Create a new account under your organization

`POST /api/v2/accounts/create-child`

Organization administrators can also have an agent create a Buyer child through
the V3 MCP preview. The agent calls `review_buyer_child_account` for a read-only
review, then `request_buyer_child_account`, which returns `approval_required`
with a link. Nothing is created until an organization administrator approves it
on the Apostra site; the agent repeats the call with the same idempotency key to
get the new account's ID. See [Account overview](https://docs.apostra.com/v2/buyer/account/overview.md) and
[Approving agent requests](https://docs.apostra.com/v2/concepts/web-approvals.md).
The review's `planCoverage` says whether the organization's plan covers a Buyer
Account; when it does not, `canRequest` is `false`, `blockers` includes
`plan_does_not_cover_account`, and `planCoverage.refusal` gives the plan it
needs and the next step.

## Availability

Creates a new account under your organization. Requires the `ADMIN` role on
the organization. An organization has no limit on how many Buyer or Seller accounts it holds, can
create at most 25 accounts in any 24 hours (the 26th returns `429 RATE_LIMITED`
with `details.reason` `account_creation_daily_limit`; contact support to raise
it, see [Accounts created per day](https://docs.apostra.com/v2/account-capacity#accounts-created-per-day)),
and holds one Developer account. If your account is standalone, you must also be its
direct administrator and explicitly confirm creation of a new organization. Present the consequences below and send the confirmation as
exactly `true`.

Advertiser objects and connected advertising-platform accounts are not
accounts of the organization and do not count toward it.

The organization created by this conversion is a billing and access container,
not a Buyer or Seller account. Your current contract and billing authority
move to it, and you become its first administrator. The existing account keeps
its role, resources, and direct members; organization administrators can manage
both accounts, while direct account members gain no organization authority.
Any account-specific standing remains an override; otherwise the account
inherits organization standing. Detachment is not self-service because it
requires a dedicated contract, billing, standing, and administrator migration.
Only a newly created `SELLER` account receives a new storefront. A new `BUYER`
account can enter Buyer Setup immediately. Its demo, real-work, direct-spend,
and Apostra-spend capabilities are derived from Organization proof, Terms,
plan/entitlements, standing, and transaction route; no separate admission flips
the Account live.

The organization's accepted plan must also cover the new account:

* a Seller Account needs a Listing plan or an Agentic Media Company plan. When
  you omit `operatingMode`, the account starts on the seller product the plan
  covers: `AGENTIC_MEDIA_COMPANY` on an Agentic Media Company plan, otherwise
  `LISTING_ONLY`. An `operatingMode` you send is kept as given, so
  `LISTING_ONLY` on an Agentic Media Company plan is refused, because a
  Listing-only storefront needs a Listing plan;
* a Buyer Account needs a buyer plan when the organization holds only Buyer
  Accounts, or an Agentic Media Company plan when it also holds Seller Accounts.
  Holding more than one Buyer Account also needs Business Manager or Enterprise.

An organization with no accepted plan can add any account. When the plan does
not cover the new account, the request is refused before anything is created,
including before a standalone account becomes an organization. The refusal names
the plan the account needs and the next step. See
[Which plan holds which accounts](https://docs.apostra.com/v2/setup/account-access.md#which-plan-holds-which-accounts).

The confirmation controls whether a fresh standalone conversion may begin. If
a matching `idempotencyKey` receipt has already committed the organization and
account hierarchy, retrying with that same key resumes required administrator
access, contract transfer, compatibility projections, and account-view repairs even
when `confirmOrganizationConversion` is omitted or `false`. The retry cannot
cancel or reverse authority that has already moved. Reusing the key with
incompatible input still returns `409 Conflict`.

## Request

Standalone conversion example:

```bash curl theme={null}
curl -X POST https://api.apostra.com/api/v2/accounts/create-child \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Retail",
    "customerRole": "BUYER",
    "idempotencyKey": "child-account:acme-retail-2026",
    "parentName": "Acme HQ",
    "customerDomain": "acmeretail.com",
    "confirmOrganizationConversion": true
  }'
```

For seller accounts, include the storefront settlement currency up front so the auto-created storefront does not require a separate currency setup step:

```json Seller account theme={null}
{
  "name": "Acme Media",
  "customerRole": "SELLER",
  "idempotencyKey": "child-account:acme-media-2026",
  "customerDomain": "acmemedia.com",
  "defaultCurrency": "USD",
  "paymentCurrencies": ["USD"]
}
```

Apostra platform administrators can instead create a leased synthetic seller:

```json Demo seller account theme={null}
{
  "name": "Acme Media Demo",
  "customerRole": "SELLER",
  "accountMode": "DEMO",
  "demoRecipeIds": ["sample-publisher-display"],
  "demoFeatureProfileName": "seller-sources/merchandising-distribution"
}
```

## Parameters

| Field | Type | Required | Notes |
| - | - | - | - |
| `name` | string | Yes | Name for the new account (1–255 chars) |
| `customerRole` | enum | Yes | Legacy request name for the account type: `BUYER`, `SELLER`, or `DEVELOPER`. A Developer account owns agents and must be created inside an organization. The first Developer account is included in every plan. Partner is an organization-level workspace and cannot be created here. |
| `idempotencyKey` | string | No | Stable key for safely retrying the same creation request (8–128 characters; letters, numbers, `.`, `_`, `:`, and `-`). Reusing a matching key resumes repairs or returns the same result; it cannot cancel committed organization attachment. |
| `parentName` | string | No | Name for the organization created during standalone conversion. Defaults to the standalone account's current name. |
| `confirmOrganizationConversion` | boolean | Standalone only | Send exactly `true` after the standalone administrator has reviewed the contract, billing, standing, membership, and detachment consequences. Omit for accounts already managed by an organization. Omission or `false` rejects a fresh conversion, but does not stop a same-key retry after its matching receipt committed the hierarchy. |
| `customerDomain` | string | No | Registered domain for the account (max 255, valid hostname). For a buyer or agents account, a domain the organization has not verified on its Domains page is refused with `400 VALIDATION_ERROR`; omit it and pick one on the account later. A `SELLER` account keeps its own brand domain, typed as before. For `BUYER`, use the domain of the operator that runs the account. For `SELLER`, use the domain of the company operating the storefront; it initially seeds the storefront's operator domain and remains separate from its public listing domain. |
| `defaultCurrency` | string | Seller | Primary storefront settlement currency. Required when `paymentCurrencies` is non-empty. |
| `paymentCurrencies` | string\[] | No | Storefront settlement currencies. For `SELLER`, include `defaultCurrency`; omit or pass `[]` to use only the primary currency. |
| `operatingMode` | enum | No | `SELLER` only: the seller product the new storefront starts with, `LISTING_ONLY` (**Just list**) or `AGENTIC_MEDIA_COMPANY` (**Create an AMC account**). When omitted, it follows the organization's accepted plan: `AGENTIC_MEDIA_COMPANY` on an Agentic Media Company plan, otherwise `LISTING_ONLY`, including for an organization with no accepted plan. A value you send is kept as given and is refused when the plan does not cover it. It decides which seller plans the organization is offered. The stored value no longer decides what the account can do: the seller's plan does, and the Storefront Agent, the Agentic Media Company product, comes with the Storefront Agent plan. See **Settings → Selling mode**. |
| `accountMode` | enum | No | Internal provisioning mode: `STANDARD` (default) or `DEMO`. `DEMO` is restricted to Apostra platform administrators and requires a `SELLER` account. |
| `demoRecipeIds` | string\[] | Demo | One to three versioned synthetic source recipes. Demo accounts must include `sample-publisher-display`. |
| `demoFeatureProfileName` | enum | No | Seller capabilities for this Demo lease: `seller-sources/listing-only`, `seller-sources/listing-distribution`, `seller-sources/merchandising`, or `seller-sources/merchandising-distribution`. Defaults to Storefront Agent + Distribution and does not change the organization's commercial profile. |

## Response

Returns the full user context scoped to the new account.
`customer.buyerAccessPosture` is deprecated and always `null`. For a Buyer,
`customer.accountProducts.core.buyerAccessPosture` is deprecated too: it is
derived from the account's capability verdicts when this response is built,
`LIVE_ELIGIBLE` when the Buyer can spend live and otherwise `SANDBOX_ONLY`, and
never stored. Neither
is an authorization source: read Buyer Setup capabilities to see what the account
can do.

```json theme={null}
{
  "user": { "id": 4412, "email": "buyer@acmeretail.com", "firstName": "Sam", "lastName": "Rivera", "role": "ADMIN" },
  "customer": {
    "id": 200,
    "company": "Acme Retail",
    "name": "Acme Retail",
    "active": true,
    "customerRole": "BUYER",
    "customerType": "CHILD",
    "nodeKind": "ACCOUNT",
    "accountType": "BUYER",
    "enabled": true,
    "buyerAccessPosture": null,
    "accountProducts": {
      "core": {
        "nodeKind": "ACCOUNT",
        "accountType": "BUYER",
        "customerId": 200,
        "enabled": true,
        "buyerAccessPosture": "SANDBOX_ONLY",
        "customerRole": "BUYER"
      },
      "partner": null
    }
  },
  "customers": [
    { "id": 100, "company": "Acme", "name": "Acme HQ", "membershipRole": "ADMIN", "role": "ADMIN", "nodeKind": "CONTAINER", "accountType": null, "enabled": true },
    { "id": 200, "company": "Acme Retail", "name": "Acme Retail", "membershipRole": "ADMIN", "role": "ADMIN", "customerRole": "BUYER", "nodeKind": "ACCOUNT", "accountType": "BUYER", "enabled": true }
  ],
  "showTosBox": false,
  "hasContract": true,
  "latestTosVersion": "2026-01",
  "convertedFromStandalone": true
}
```

| Field | Type | Notes |
| - | - | - |
| `user` | object | User profile data |
| `customer` | object | Context for the newly created account. Canonical fields include `nodeKind`, `accountType`, and `enabled`; `customerRole` and `buyerAccessPosture` remain as deprecated compatibility fields. |
| `customers` | array | All organizations and accounts the user can access. `accountType` remains the legacy Buyer/Seller compatibility value; optional `accountKind` is the product kind and reports `DEVELOPER` for Developer accounts. |
| `showTosBox` | boolean | Whether to show the ToS acceptance dialog |
| `organizationContractMissing` | boolean (optional) | Included as `true` when the inherited organization has no active contract; otherwise omitted. Block usage until an org admin accepts ToS. |
| `hasContract` | boolean | Whether the account has an active contract |
| `latestTosVersion` | string | Latest Terms of Service version identifier |
| `convertedFromStandalone` | boolean | `true` if the request triggered a standalone-to-organization conversion |

## Errors

* `400 VALIDATION_ERROR` — missing required field, `customerDomain` fails the hostname pattern, or `customerDomain` is not one of the organization's verified domains (buyer and agents accounts).
* `401 UNAUTHORIZED` — missing or invalid bearer token.
* `403 ACCESS_DENIED` — caller is not an administrator.
* `409 CONFLICT` with `details.resource` `developer_account_limit` — the organization already has a Developer account. An organization holds one, and it can hold any number of agents.
* `409 CONFLICT` — a fresh standalone conversion omitted `confirmOrganizationConversion: true` or sent `false`, or the request reused an idempotency key with incompatible input. A matching same-key retry after the hierarchy committed resumes instead of returning this confirmation error.
* `409 CONFLICT` with `details.reason` `plan_does_not_cover_account` — the organization's accepted plan does not cover the new account. `details.requiredPlans` lists the plan families that would (`BUYER`, `LISTING`, `PARTNER`, `AGENTIC_MEDIA_COMPANY`; empty when no plan you can choose covers it), `details.nextStep` names what to do first (`switch_seller_product`, `change_plan`, `use_agentic_media_company_seller_product`, or `get_in_touch`), and, for members of the organization, `details.currentPlan` names the plan it is on. On a Listing plan, `details.nextPlan` is `standard`: adding a Buyer Account needs the Standard plan. When the next step is to change the plan, `details.planSwitch` carries the typed next step (`switch_plan`) and, for an administrator of the organization, the **Plan & pricing** link. A same-key retry of a creation that already committed is not refused.

See [Errors](https://docs.apostra.com/v2/reference/errors.md) for the full error contract.

## Related

> [card] [Account tasks](https://docs.apostra.com/v2/buyer/account/tasks.md)
>
> All account operations

> [card] [Delete account](https://docs.apostra.com/v2/buyer/account/tasks/delete-child-account)
>
> Remove an account from your organization

> [card] [Update account domain](https://docs.apostra.com/v2/buyer/account/tasks/update-customer-domain.md)
>
> Set the registered domain


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