> ## 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
> Provision a new buyer or seller account under your organization
`POST /api/v2/accounts/create-child`
## Availability
Creates a new account under your organization. Requires the `ADMIN` role on
the organization and an accepted package with an unused account slot. If your
account is standalone, the package must include at least two account slots. 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`.
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 legal, 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 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, deprecated Buyer 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
```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": "Northwind Retail",
"customerRole": "SELLER",
"idempotencyKey": "child-account:northwind-retail-2026",
"customerDomain": "retail.northwind.example",
"defaultCurrency": "USD",
"paymentCurrencies": ["USD"]
}'
```
```json With standalone conversion theme={null}
{
"name": "Northwind Buying",
"customerRole": "BUYER",
"idempotencyKey": "child-account:northwind-buying-2026",
"parentName": "Northwind HQ",
"confirmOrganizationConversion": true
}
```
```json Demo seller account (Apostra platform administrators only) theme={null}
{
"name": "Northwind Demo",
"customerRole": "SELLER",
"accountMode": "DEMO",
"demoRecipeIds": ["sample-publisher-display", "sample-publisher-ctv"],
"demoFeatureProfileName": "seller-sources/merchandising-distribution"
}
```
## Parameters
| Field | Type | Required | Notes |
| ------------------------------- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | string | Yes | Name for the new account (max 255) |
| `customerRole` | enum | Yes | Legacy request name for the account type: `BUYER` or `SELLER`. 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. 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. Include `defaultCurrency`; omit or pass `[]` to use only the primary currency. |
| `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 Merchandising + Distribution. This does not assign a commercial profile to the organization. |
## Response
`buyerAccessPosture` remains in this response only as a deprecated compatibility
projection and must not be used for authorization. Read Buyer Setup capabilities.
```json theme={null}
{
"user": { "id": 4412, "email": "ops@northwind.example", "firstName": "Sam", "lastName": "Rivera", "role": "ADMIN" },
"customer": { "id": 200, "company": "Northwind Buying", "name": "Northwind Buying", "active": true, "customerRole": "BUYER", "customerType": "CHILD", "nodeKind": "ACCOUNT", "accountType": "BUYER", "enabled": true, "buyerAccessPosture": "SANDBOX_ONLY", "accountProducts": { "core": { "nodeKind": "ACCOUNT", "accountType": "BUYER", "customerId": 200, "enabled": true, "buyerAccessPosture": "SANDBOX_ONLY", "customerRole": "BUYER" }, "partner": null } },
"customers": [
{ "id": 100, "company": "Northwind HQ", "name": "Northwind HQ", "membershipRole": "ADMIN", "role": "ADMIN", "nodeKind": "CONTAINER", "accountType": null, "enabled": true },
{ "id": 90, "company": "Northwind Retail", "name": "Northwind Retail", "membershipRole": "ADMIN", "role": "ADMIN", "customerRole": "SELLER", "nodeKind": "ACCOUNT", "accountType": "SELLER", "enabled": true },
{ "id": 200, "company": "Northwind Buying", "name": "Northwind Buying", "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 | Your user profile scoped to the new account |
| `customer` | object | Context for the newly created account. Canonical fields include `nodeKind`, `accountType`, and `enabled`; `customerRole` and Buyer `buyerAccessPosture` remain as deprecated compatibility projections. |
| `customers[]` | array | All organizations and accounts you can now access, including canonical `nodeKind`, `accountType`, `enabled`, and `membershipRole` fields. |
| `showTosBox` | boolean | Whether to surface the ToS acceptance dialog |
| `organizationContractMissing` | boolean (optional) | Included as `true` when the new account cannot operate because its organization has no active contract; otherwise omitted. |
| `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 `name`/`customerRole`, or a malformed `customerDomain`.
* `401 UNAUTHORIZED` — authentication is missing or invalid.
* `403 ACCESS_DENIED` — caller is not an administrator, or the organization has no active package granting account capacity.
* `409 CONFLICT` — no account slot remains, 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.
See [Errors](/v2/reference/errors) for the full error contract.
## Related
All account operations
Remove an empty account
See the new account