Create account

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. The organization created by this conversion is a billing and access container, not a buyer or storefront account. The existing account keeps its role and resources; only a newly created SELLER account receives a new storefront.

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

Field	Type	Required	Notes
`name`	string	Yes	Name for the new account (max 255)
`customerRole`	enum	Yes	`BUYER` or `SELLER`
`parentName`	string	No	Name for the organization created during standalone conversion. Defaults to `"{company} (Admin)"`
`customerDomain`	string	No	Registered 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.
`defaultCurrency`	string	Seller	Primary storefront settlement currency. Required when `paymentCurrencies` is non-empty.
`paymentCurrencies`	string[]	No	Storefront 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
}

Field	Type	Notes
`user`	object	Your user profile scoped to the new account
`customer`	object	Context for the newly created account
`customers[]`	array	All accounts you can now access
`showTosBox`	boolean	Whether to surface the ToS acceptance dialog
`organizationContractMissing`	boolean	True when the new account cannot operate because its organization has no active contract
`hasContract`	boolean	Whether the account has an active contract
`latestTosVersion`	string	Latest embedded sales agent version identifier
`convertedFromStandalone`	boolean	True 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

Account tasks Delete account

⌘I

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

Request

Parameters

Response

Errors

Account tasks

Delete account

List accounts

​Request

​Parameters

​Response

​Errors

​Related

Account tasks

Delete account

List accounts

Request

Parameters

Response

Errors

Related