Skip to main content
Deprecated. This page documents the v2 storefront API, which is being retired for external callers. Use Navigation and shared tools in V3 instead.
The account endpoints expose your current storefront account. Use them to read its context, list accounts you can switch into, set the registered company domain, control domain auto-join, and manage notification opt-ins.

​
Account model

Full user-context responses returned by account creation and switching use nodeKind to distinguish a Buyer or Seller account from an organization container. accountType is the canonical product field for those accounts; customerRole remains as a compatibility field for Buyer and Seller integrations. Some compatibility responses use accountType: PARTNER to project the organization’s sales-agent offering. That projection is not a separate account and has no legacy customerRole equivalent. enabled only controls whether people and API clients can enter the account. It does not make a Buyer live-eligible or grant Commercial Partner approval. The buyerAccessPosture on the account’s user context is deprecated and never operation authority: customer.buyerAccessPosture is always null, and a Buyer’s accountProducts.core.buyerAccessPosture is derived from its capability verdicts on every read (SANDBOX_ONLY unless the Buyer can spend live). Buyer Setup derives the applicable Buyer capabilities instead. Sales-agent offering projections expose registration as AVAILABLE or REGISTERED and commercial status as INACTIVE, ACTIVE, SUSPENDED, or EXITED. A newly enabled offering starts AVAILABLE / INACTIVE, so enabling, registration, or certification never implies commercial access. All examples use the storefront base URL:
Authenticate every request with Authorization: Bearer $SCOPE3_API_KEY. Your account context is resolved from the API key. Domain and membership operations require the ADMIN role on the target account.

​
Key concepts

  • Registered domain. An account can carry one customerDomain. It gates domain auto-join and, for SELLER accounts, identifies the company operating the storefront. It initially seeds the storefront’s operator domain and remains separate from its public listing domain.
  • Storefront operator domain. A storefront has its own operatorDomain, which is the canonical domain the storefront operates as for AAO and buyer-facing identity. It may differ from the account’s customerDomain. Updating customerDomain syncs the storefront only while the storefront operator domain is missing or still mirrors the account’s previous registered domain.
  • Domain auto-join. Users with a verified matching-domain email join as members without admin approval when allowDomainAutoJoin is true. It defaults on for top-level organizations and off for child accounts, and requires a customerDomain to be set. Admins can explicitly override the default.
  • Notification opt-ins. Preferences are a full set of { notificationType, channel } pairs. The update call replaces all existing opt-ins.

​
Manage child accounts in the app

Organization administrators can open Settings → Organization → Accounts from the organization or one of its child accounts. This pane lists the organization’s child accounts, links to each active account’s members, and provides Add account, Archive, and Restore. Creation follows the organization’s account-capacity rules. Archive shows any campaign or media-buy blockers before you confirm; archived accounts retain their history and still count toward capacity. A user with billing access who does not get the Organization section, such as an Apostra platform administrator who is not a member of the organization, manages child accounts in Plan & Billing → Accounts. That tab also shows account usage, fees when available, and agreement history.

​
Manage accounts with a V3 agent

From an organization in the V3 MCP preview, use search({kind: "account"}) to list its active and archived child accounts. Use get({kind: "account", id: "<account-id>"}) for one account. The detail includes its ACTIVE or ARCHIVED lifecycle status and the organization’s commercial terms that the account inherits: the current Terms of Service URL, required and accepted versions, acceptance details, current contract posture, and up to 25 agreement-history entries. These terms belong to the organization; they are not separate child-account terms. Use search({kind: "member", filter: {accountId: <account-id>}}) to read an account roster, then get({kind: "member", id: "<member-id>", memberAccountId: <account-id>}) for one membership and role. Member reads do not grant or change access. Organization administrators manage child accounts (create, rename, archive and restore) with the V3 tools; see Manage organization accounts. The earlier manage_organization task has been removed.

​
Task reference

Get current account

Authenticated account context

List accounts

Accounts you can switch into

Update account domain

Set the account’s registered domain

Get membership

Read domain auto-join setting

Update membership

Toggle domain auto-join

Get notification preferences

Read your opt-ins

Update notification preferences

Replace your opt-ins

All account tasks

Every operation in one place

Activity & reporting

Audit feed and reporting metrics

Errors

Shared error contract