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

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

​
Parameters

FieldTypeRequiredNotes
namestringYesName for the new account (1–255 chars)
customerRoleenumYesBUYER or SELLER
parentNamestringNoName for the organization created during standalone conversion (1–255). Defaults to "{company} (Admin)"
customerDomainstringNoRegistered domain for the account (max 255, valid hostname). For SELLER, also seeds the auto-created storefront’s publisher and operator domain
defaultCurrencystringSellerPrimary storefront settlement currency. Required when paymentCurrencies is non-empty.
paymentCurrenciesstring[]NoStorefront 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. 
{
  "user": {},
  "customer": {},
  "customers": [],
  "showTosBox": false,
  "organizationContractMissing": false,
  "hasContract": true,
  "latestTosVersion": "2026-01",
  "convertedFromStandalone": true
}
FieldTypeNotes
userobjectUser profile data
customerobjectContext for the newly created account
customersarrayAll accounts the user can access
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 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 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 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