Skip to main content
The account endpoints expose the organization behind your storefront. Use them to read your current account context, list the accounts you can switch into, provision and remove accounts under your organization, set the registered account domain, control domain auto-join, and manage your 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. Some compatibility responses still expose buyerAccessPosture; it is deprecated and is never operation authority. 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. Creating another managed account requires organization-administrator authority; clients converting a standalone account require direct administrator authority on that account plus explicit confirmation of the organization setup. For a fresh conversion, the confirmation must be exactly true; omission or false returns 409 Conflict before the hierarchy changes. Once a matching idempotency receipt has committed the hierarchy, retries with the same key instead resume required administrator, contract, deprecated Buyer compatibility projections, and account-view repairs even if confirmation is omitted or false. A retry cannot cancel or reverse authority that has already moved.

​
Key concepts

  • Organization/account hierarchy. Clients explicitly confirm organization creation while adding another account from a standalone account. The new organization receives contract and billing authority, its administrators can manage both attached accounts, and each account otherwise preserves its own resources and direct members. Account-specific standing remains an override; absent one, standing inherits from the organization. Detachment is not self-service because restoring independent contract, billing, standing, and administrator authority requires a dedicated migration. Only CHILD-type accounts can be deleted, and only when they have no linked resources.
  • Registered domain. An account can carry one customerDomain. It gates domain auto-join and, for SELLER accounts, seeds the auto-created storefront’s publisher and operator domain when supplied.
  • 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.

​
Task reference

Get current account

Authenticated account context

List accounts

Accounts you can switch into

Create account

Provision a buyer or seller account

Delete account

Hard-delete an empty account

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