Skip to main content
POST /api/v2/accounts/create-child Creates a new child customer account. If the current customer is standalone, this first converts it into a parent and creates the parent/child hierarchy. Requires ADMIN role.

​
Request

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

​
Parameters

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

​
Response

Returns the full user context scoped to the new child customer. 
{
  "user": {},
  "customer": {},
  "customers": [],
  "showTosBox": false,
  "organizationContractMissing": false,
  "hasContract": true,
  "latestTosVersion": "2026-01",
  "convertedFromStandalone": true
}
FieldTypeNotes
userobjectUser profile data
customerobjectCustomer context for the newly created child
customersarrayAll accessible customer accounts
showTosBoxbooleanWhether to show the ToS acceptance dialog
organizationContractMissingbooleantrue when the inherited organization has no active contract; block usage until an org admin accepts ToS
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 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 customer.
See Errors for the full error contract.

Account tasks

All account operations

Delete child account

Remove a child customer

Update customer domain

Set the org domain