> ## 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

> Create a new account under your organization

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

Creates a new account under your organization. If the current account is standalone, this first converts it into an organization and creates the organization/account hierarchy. Requires `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

```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": "Acme Retail",
    "customerRole": "BUYER",
    "parentName": "Acme HQ",
    "customerDomain": "acmeretail.com"
  }'
```

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",
  "customerDomain": "acmemedia.com",
  "defaultCurrency": "USD",
  "paymentCurrencies": ["USD"]
}
```

## Parameters

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

## Response

Returns the full user context scoped to the new account.

```json theme={null}
{
  "user": {},
  "customer": {},
  "customers": [],
  "showTosBox": false,
  "organizationContractMissing": false,
  "hasContract": true,
  "latestTosVersion": "2026-01",
  "convertedFromStandalone": true
}
```

| Field                         | Type    | Notes                                                                                                     |
| ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `user`                        | object  | User profile data                                                                                         |
| `customer`                    | object  | Context for the newly created account                                                                     |
| `customers`                   | array   | All accounts the user can access                                                                          |
| `showTosBox`                  | boolean | Whether to show the ToS acceptance dialog                                                                 |
| `organizationContractMissing` | boolean | `true` when the inherited organization has no active contract; block usage until an org admin accepts ToS |
| `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 required field or `customerDomain` fails the hostname pattern.
* `401 UNAUTHORIZED` — missing or invalid bearer token.
* `403 FORBIDDEN` — caller is not an `ADMIN` on the current account.

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

## Related

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

  <Card title="Delete account" href="/v2/buyer/account/tasks/delete-child-account" icon="trash">
    Remove an account from your organization
  </Card>

  <Card title="Update account domain" href="/v2/buyer/account/tasks/update-customer-domain" icon="globe">
    Set the registered domain
  </Card>
</CardGroup>