Skip to main content
POST /api/v2/accounts/create-child Creates a new child customer account. If your account is still standalone, the call first converts it into a parent and nests the new account underneath. Requires the ADMIN role.

​
Request

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"
  }'

​
Parameters

FieldTypeRequiredNotes
namestringYesName for the new child account (max 255)
customerRoleenumYesBUYER or SELLER
parentNamestringNoName for the parent created during standalone conversion. Defaults to "{company} (Admin)"
customerDomainstringNoRegistered organization domain. For SELLER accounts, also seeds the auto-created storefront’s publisher and operator domain

​
Response

{
  "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
}
FieldTypeNotes
userobjectYour user profile scoped to the new child
customerobjectContext for the newly created child
customers[]arrayAll accounts you can now access
showTosBoxbooleanWhether to surface the ToS acceptance dialog
organizationContractMissingbooleanTrue when the child cannot operate because its inherited organization has no active contract
hasContractbooleanWhether the customer has an active contract
latestTosVersionstringLatest embedded sales agent version identifier
convertedFromStandalonebooleanTrue if the request triggered a standalone-to-parent conversion

​
Errors

  • 400 VALIDATION_ERROR — missing name/customerRole, or a malformed customerDomain.
  • 401 UNAUTHORIZED — caller is not an ADMIN.
See Errors for the full error contract.

Account tasks

All account operations

Delete child account

Remove an empty child

List customer accounts

See the new child