Create account

POST /api/v2/accounts/create-child Organization administrators can also have an agent create a Buyer child through the V3 MCP preview. The agent calls review_buyer_child_account for a read-only review, then request_buyer_child_account, which returns approval_required with a link. Nothing is created until an organization administrator approves it on the Apostra site; the agent repeats the call with the same idempotency key to get the new account’s ID. See Account overview and Approving agent requests. The review’s planCoverage says whether the organization’s plan covers a Buyer Account; when it does not, canRequest is false, blockers includes plan_does_not_cover_account, and planCoverage.refusal gives the plan it needs and the next step.

Availability

Creates a new account under your organization. Requires the ADMIN role on the organization. An organization has no limit on how many Buyer or Seller accounts it holds, can create at most 25 accounts in any 24 hours (the 26th returns 429 RATE_LIMITED with details.reason account_creation_daily_limit; contact support to raise it, see Accounts created per day), and holds one Developer account. If your account is standalone, you must also be its direct administrator and explicitly confirm creation of a new organization. Present the consequences below and send the confirmation as exactly true. Advertiser objects and connected advertising-platform accounts are not accounts of the organization and do not count toward it. The organization created by this conversion is a billing and access container, not a Buyer or Seller account. Your current contract and billing authority move to it, and you become its first administrator. The existing account keeps its role, resources, and direct members; organization administrators can manage both accounts, while direct account members gain no organization authority. Any account-specific standing remains an override; otherwise the account inherits organization standing. Detachment is not self-service because it requires a dedicated contract, billing, standing, and administrator migration. Only a newly created SELLER account receives a new storefront. A new BUYER account can enter Buyer Setup immediately. Its demo, real-work, direct-spend, and Apostra-spend capabilities are derived from Organization proof, Terms, plan/entitlements, standing, and transaction route; no separate admission flips the Account live. The organization’s accepted plan must also cover the new account:

a Seller Account needs a Listing plan or an Agentic Media Company plan. When you omit operatingMode, the account starts on the seller product the plan covers: AGENTIC_MEDIA_COMPANY on an Agentic Media Company plan, otherwise LISTING_ONLY. An operatingMode you send is kept as given, so LISTING_ONLY on an Agentic Media Company plan is refused, because a Listing-only storefront needs a Listing plan;
a Buyer Account needs a buyer plan when the organization holds only Buyer Accounts, or an Agentic Media Company plan when it also holds Seller Accounts. Holding more than one Buyer Account also needs Business Manager or Enterprise.

An organization with no accepted plan can add any account. When the plan does not cover the new account, the request is refused before anything is created, including before a standalone account becomes an organization. The refusal names the plan the account needs and the next step. See Which plan holds which accounts. The confirmation controls whether a fresh standalone conversion may begin. If a matching idempotencyKey receipt has already committed the organization and account hierarchy, retrying with that same key resumes required administrator access, contract transfer, compatibility projections, and account-view repairs even when confirmOrganizationConversion is omitted or false. The retry cannot cancel or reverse authority that has already moved. Reusing the key with incompatible input still returns 409 Conflict.

Request

Standalone conversion example:

curl

curl -X POST https://api.apostra.com/api/v2/accounts/create-child \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Retail",
    "customerRole": "BUYER",
    "idempotencyKey": "child-account:acme-retail-2026",
    "parentName": "Acme HQ",
    "customerDomain": "acmeretail.com",
    "confirmOrganizationConversion": true
  }'

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",
  "idempotencyKey": "child-account:acme-media-2026",
  "customerDomain": "acmemedia.com",
  "defaultCurrency": "USD",
  "paymentCurrencies": ["USD"]
}

Apostra platform administrators can instead create a leased synthetic seller:

Demo seller account

{
  "name": "Acme Media Demo",
  "customerRole": "SELLER",
  "accountMode": "DEMO",
  "demoRecipeIds": ["sample-publisher-display"],
  "demoFeatureProfileName": "seller-sources/merchandising-distribution"
}

Parameters

Field	Type	Required	Notes
`name`	string	Yes	Name for the new account (1–255 chars)
`customerRole`	enum	Yes	Legacy request name for the account type: `BUYER`, `SELLER`, or `DEVELOPER`. A Developer account owns agents and must be created inside an organization. The first Developer account is included in every plan. Partner is an organization-level workspace and cannot be created here.
`idempotencyKey`	string	No	Stable key for safely retrying the same creation request (8–128 characters; letters, numbers, `.`, `_`, `:`, and `-`). Reusing a matching key resumes repairs or returns the same result; it cannot cancel committed organization attachment.
`parentName`	string	No	Name for the organization created during standalone conversion. Defaults to the standalone account’s current name.
`confirmOrganizationConversion`	boolean	Standalone only	Send exactly `true` after the standalone administrator has reviewed the contract, billing, standing, membership, and detachment consequences. Omit for accounts already managed by an organization. Omission or `false` rejects a fresh conversion, but does not stop a same-key retry after its matching receipt committed the hierarchy.
`customerDomain`	string	No	Registered domain for the account (max 255, valid hostname). For `BUYER`, use the domain of the operator that runs the account. For `SELLER`, use the domain of the company operating the storefront; it initially seeds the storefront’s operator domain and remains separate from its public listing domain.
`defaultCurrency`	string	Seller	Primary storefront settlement currency. Required when `paymentCurrencies` is non-empty.
`paymentCurrencies`	string[]	No	Storefront settlement currencies. For `SELLER`, include `defaultCurrency`; omit or pass `[]` to use only the primary currency.
`operatingMode`	enum	No	`SELLER` only: the seller product the new storefront starts with, `LISTING_ONLY` (Just list) or `AGENTIC_MEDIA_COMPANY` (Create an AMC account). When omitted, it follows the organization’s accepted plan: `AGENTIC_MEDIA_COMPANY` on an Agentic Media Company plan, otherwise `LISTING_ONLY`, including for an organization with no accepted plan. A value you send is kept as given and is refused when the plan does not cover it. It decides which seller plans the organization is offered. The stored value no longer decides what the account can do: the seller’s plan does, and Merchandising, the Agentic Media Company product, comes with the Merchandising plan. See Settings → Selling mode.
`accountMode`	enum	No	Internal provisioning mode: `STANDARD` (default) or `DEMO`. `DEMO` is restricted to Apostra platform administrators and requires a `SELLER` account.
`demoRecipeIds`	string[]	Demo	One to three versioned synthetic source recipes. Demo accounts must include `sample-publisher-display`.
`demoFeatureProfileName`	enum	No	Seller capabilities for this Demo lease: `seller-sources/listing-only`, `seller-sources/listing-distribution`, `seller-sources/merchandising`, or `seller-sources/merchandising-distribution`. Defaults to Merchandising + Distribution and does not change the organization’s commercial profile.

Response

Returns the full user context scoped to the new account. customer.buyerAccessPosture is deprecated and always null. For a Buyer, customer.accountProducts.core.buyerAccessPosture is deprecated too: it is derived from the account’s capability verdicts when this response is built, LIVE_ELIGIBLE when the Buyer can spend live and otherwise SANDBOX_ONLY, and never stored. Neither is an authorization source: read Buyer Setup capabilities to see what the account can do.

{
  "user": { "id": 4412, "email": "buyer@acmeretail.com", "firstName": "Sam", "lastName": "Rivera", "role": "ADMIN" },
  "customer": {
    "id": 200,
    "company": "Acme Retail",
    "name": "Acme Retail",
    "active": true,
    "customerRole": "BUYER",
    "customerType": "CHILD",
    "nodeKind": "ACCOUNT",
    "accountType": "BUYER",
    "enabled": true,
    "buyerAccessPosture": null,
    "accountProducts": {
      "core": {
        "nodeKind": "ACCOUNT",
        "accountType": "BUYER",
        "customerId": 200,
        "enabled": true,
        "buyerAccessPosture": "SANDBOX_ONLY",
        "customerRole": "BUYER"
      },
      "partner": null
    }
  },
  "customers": [
    { "id": 100, "company": "Acme", "name": "Acme HQ", "membershipRole": "ADMIN", "role": "ADMIN", "nodeKind": "CONTAINER", "accountType": null, "enabled": true },
    { "id": 200, "company": "Acme Retail", "name": "Acme Retail", "membershipRole": "ADMIN", "role": "ADMIN", "customerRole": "BUYER", "nodeKind": "ACCOUNT", "accountType": "BUYER", "enabled": true }
  ],
  "showTosBox": false,
  "hasContract": true,
  "latestTosVersion": "2026-01",
  "convertedFromStandalone": true
}

Field	Type	Notes
`user`	object	User profile data
`customer`	object	Context for the newly created account. Canonical fields include `nodeKind`, `accountType`, and `enabled`; `customerRole` and `buyerAccessPosture` remain as deprecated compatibility fields.
`customers`	array	All organizations and accounts the user can access. `accountType` remains the legacy Buyer/Seller compatibility value; optional `accountKind` is the product kind and reports `DEVELOPER` for Developer accounts.
`showTosBox`	boolean	Whether to show the ToS acceptance dialog
`organizationContractMissing`	boolean (optional)	Included as `true` when the inherited organization has no active contract; otherwise omitted. Block usage until an org admin accepts ToS.
`hasContract`	boolean	Whether the account has an active contract
`latestTosVersion`	string	Latest Terms of Service version identifier
`convertedFromStandalone`	boolean	`true` 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 ACCESS_DENIED — caller is not an administrator.
409 CONFLICT with details.resource developer_account_limit — the organization already has a Developer account. An organization holds one, and it can hold any number of agents.
409 CONFLICT — a fresh standalone conversion omitted confirmOrganizationConversion: true or sent false, or the request reused an idempotency key with incompatible input. A matching same-key retry after the hierarchy committed resumes instead of returning this confirmation error.
409 CONFLICT with details.reason plan_does_not_cover_account — the organization’s accepted plan does not cover the new account. details.requiredPlans lists the plan families that would (BUYER, LISTING, PARTNER, AGENTIC_MEDIA_COMPANY; empty when no plan you can choose covers it), details.nextStep names what to do first (switch_seller_product, change_plan, use_agentic_media_company_seller_product, or get_in_touch), and, for members of the organization, details.currentPlan names the plan it is on. On a Listing plan, details.nextPlan is standard: adding a Buyer Account needs the Standard plan. When the next step is to change the plan, details.planSwitch carries the typed next step (switch_plan) and, for an administrator of the organization, the Plan & pricing link. A same-key retry of a creation that already committed is not refused.

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

Start here

Buy media

Sell media

Help and updates

Availability

Request

Parameters

Response

Errors

Account tasks

Delete account

Update account domain

​Availability

​Request

​Parameters

​Response

​Errors

​Related

Account tasks

Delete account

Update account domain

Availability

Request

Parameters

Response

Errors

Related