> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/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`

Creates a new account under your organization. If your account is still standalone, the call first converts it into an organization and nests the new account underneath. Requires the `ADMIN` role.

The organization created by this conversion is a billing and access container,
not a buyer or storefront account. The existing account keeps its role and
resources; only a newly created `SELLER` account receives a new storefront.

## Request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.interchange.io/api/v2/accounts/create-child \
    -H "Authorization: Bearer $SCOPE3_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Northwind Retail",
      "customerRole": "SELLER",
      "customerDomain": "retail.northwind.example",
      "defaultCurrency": "USD",
      "paymentCurrencies": ["USD"]
    }'
  ```

  ```json With standalone conversion theme={null}
  {
    "name": "Northwind Buying",
    "customerRole": "BUYER",
    "parentName": "Northwind HQ"
  }
  ```
</CodeGroup>

## Parameters

| Field               | Type      | Required | Notes                                                                                                                                                                                                       |
| ------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`              | string    | Yes      | Name for the new account (max 255)                                                                                                                                                                          |
| `customerRole`      | enum      | Yes      | `BUYER` or `SELLER`                                                                                                                                                                                         |
| `parentName`        | string    | No       | Name for the organization created during standalone conversion. Defaults to `"{company} (Admin)"`                                                                                                           |
| `customerDomain`    | string    | No       | Registered domain for the account. For `SELLER` accounts, also seeds the auto-created storefront's publisher and operator domain. The storefront operator domain can later diverge from the account 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.                                                                                            |

## Response

```json theme={null}
{
  "user": { "id": 4412, "email": "ops@northwind.example", "firstName": "Sam", "lastName": "Rivera", "role": "ADMIN" },
  "customer": { "id": 200, "company": "Northwind", "name": "Northwind Retail", "active": true, "customerRole": "SELLER", "customerType": "CHILD" },
  "customers": [
    { "id": 100, "company": "Northwind", "name": "Northwind (Admin)", "role": "ADMIN", "customerType": "PARENT" },
    { "id": 200, "company": "Northwind", "name": "Northwind Retail", "role": "ADMIN", "customerType": "CHILD" }
  ],
  "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                                                    |
| `customers[]`                 | array   | All accounts you can now access                                                          |
| `showTosBox`                  | boolean | Whether to surface the ToS acceptance dialog                                             |
| `organizationContractMissing` | boolean | True when the new account cannot operate because its organization has no active contract |
| `hasContract`                 | boolean | Whether the account has an active contract                                               |
| `latestTosVersion`            | string  | Latest embedded sales agent 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` — caller is not an `ADMIN`.

See [Errors](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Account tasks" href="/v2/storefront/account/tasks" icon="list-check">
    All account operations
  </Card>

  <Card title="Delete account" href="/v2/storefront/account/tasks/delete-child-account" icon="trash">
    Remove an empty account
  </Card>

  <Card title="List accounts" href="/v2/storefront/account/tasks/list-customer-accounts" icon="list">
    See the new account
  </Card>
</CardGroup>