Skip to main content
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.

​
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",
    "defaultCurrency": "USD",
    "paymentCurrencies": ["USD"]
  }'

{
  "name": "Northwind Buying",
  "customerRole": "BUYER",
  "parentName": "Northwind HQ"
}

​
Parameters

FieldTypeRequiredNotes
namestringYesName for the new account (max 255)
customerRoleenumYesBUYER or SELLER
parentNamestringNoName for the organization created during standalone conversion. Defaults to "{company} (Admin)"
customerDomainstringNoRegistered 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.
defaultCurrencystringSellerPrimary storefront settlement currency. Required when paymentCurrencies is non-empty.
paymentCurrenciesstring[]NoStorefront settlement currencies. Include defaultCurrency; omit or pass [] to use only the primary currency.

​
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 account
customerobjectContext for the newly created account
customers[]arrayAll accounts you can now access
showTosBoxbooleanWhether to surface the ToS acceptance dialog
organizationContractMissingbooleanTrue when the new account cannot operate because its organization has no active contract
hasContractbooleanWhether the account has an active contract
latestTosVersionstringLatest embedded sales agent version identifier
convertedFromStandalonebooleanTrue 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 for the full error contract.

Account tasks

All account operations

Delete account

Remove an empty account

List accounts

See the new account