Create account

POST /api/v2/accounts/create-child Creates a new account under your organization. Requires the ADMIN role on the organization. If your account is standalone, you must instead 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 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 Interchange-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, 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:

curl

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",
    "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:

Seller account

{
  "name": "Acme Media",
  "customerRole": "SELLER",
  "idempotencyKey": "child-account:acme-media-2026",
  "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	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 (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. buyerAccessPosture remains in this response only as a deprecated compatibility projection and must not be used for authorization. Read Buyer Setup capabilities.

{
  "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": "SANDBOX_ONLY",
    "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 Buyer `buyerAccessPosture` remain as deprecated compatibility projections.
`customers`	array	All organizations and accounts the user can access, including canonical `nodeKind`, `accountType`, `enabled`, and `membershipRole` fields.
`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 or customerDomain fails the hostname pattern.
401 UNAUTHORIZED — missing or invalid bearer token.
403 ACCESS_DENIED — caller is not an administrator of the organization, or a direct administrator of the standalone account being converted.
409 CONFLICT — a fresh standalone conversion omitted confirmOrganizationConversion: true, sent false, or 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 for the full error contract.

Account tasks

All account operations

Delete account

Remove an account from your organization

Update account domain

Set the registered domain

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Request

Parameters

Response

Errors

Account tasks

Delete account

Update account domain

​Request

​Parameters

​Response

​Errors

​Related

Account tasks

Delete account

Update account domain

Request

Parameters

Response

Errors

Related