> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Buyer setup and go-live

> Set up your operator once, then see what each seller or buying platform needs.

Buyer Setup separates your organization’s platform readiness from the setup for
each seller or buying platform.

Buyer and Seller Setup use the same activation pattern: a neutral status and
progress header, one operator-domain editor, and a clear next action. They are
separate Pages because the work after identity is different. Buyers configure
destinations and advertiser mappings; storefronts configure inventory,
publisher authorization, settlement, and payouts.

## Platform go-live

You complete these steps once for the buyer account:

* confirm the domain of the organization operating the account;
* say whether the account represents the whole operator or a specific operating
  unit;
* choose the plan for this buyer account;
* accept the current terms; and
* resolve any account hold.

These facts unlock real non-spend work such as connections, proposals,
campaign setup, and a credit application. An eligible payment method or
approved credit authority is needed only when a transaction's seller bills
through Apostra.

Together, the domain and optional operating-unit ID form the account's AdCP
operator identity:

| Account scope      | Operator identity                                    |
| ------------------ | ---------------------------------------------------- |
| The whole operator | The operator domain, with no operating unit          |
| A specific unit    | The operator domain plus a stable `operator_unit.id` |

Use a specific unit for a buying seat, office, region, or team that needs to be
distinguishable from other accounts under the same domain. Prefer a code your
organization already uses. If you do not have one, use a short, readable ID
that will remain meaningful over time. Do not use `default`, a temporary display
name, a seller's account ID, or an Apostra database ID. The buyer account
name is mutable display metadata; the billing-company name is separate and does
not identify the operating unit.

An account administrator must confirm the scope. Before confirming, review the
other buyer accounts under the same operator domain so you do not claim the
whole operator when the account actually represents one unit. Buyer Setup lists
the confirmed identities visible in your account hierarchy for the domain you
enter. Apostra rejects an exact identity already claimed by another buyer
account. You can change the operator domain, scope, or unit ID after setup and
after connecting storefronts, until an advertiser account is created or bound
under that identity. Buyer Setup then reports the identity as locked. In AdCP
3.2, the operator domain and optional operating-unit ID are advertiser natural-key
dimensions; pre-3.2 bindings still make the seller-visible operator domain
immutable. Changing either requires an advertiser identity migration rather
than an ordinary settings update.

Apostra compares the operator domain with account membership and the
verified organization domain. The Organization must prove control before real
operations are available. AAO corporate metadata can suggest or classify the
Organization, but a public AAO record is not ownership proof. A buyer operator does not publish
`adagents.json`; that document belongs to seller authorization. Buyer setup also
does not require `brand.json`.

Buyer Setup always shows the current operator. A domain suggested from existing
account or work-email information is prefilled, but it is not silently treated
as your choice. A sole buyer account may show **The whole operator** as a
recommendation; an administrator still confirms it. When the account is a
specific unit, Buyer Setup proposes a readable ID from the account name, which
you should replace when your organization has an established code.

Existing accounts with a proved legacy domain remain able to use their existing
buying paths while scope confirmation is pending. Buyer Setup continues to mark
the operator-identity step as incomplete, and new AdCP 3.2 provisioning may
require the complete confirmed identity.

## If an API call requires Buyer Setup

On `/mcp/v3`, call `get_status` first. When
`operatorIdentity.usableForBuying` is false, an account administrator can call
`save_buyer_operator` with the real non-platform `operatorDomain` and either
`operatorScope: "whole_operator"` or `operatorScope: "specific_unit"` plus a
stable `operatorUnitId`. When the domain is usable but `scopeStatus` is
`unclassified` and `locked` is false, reuse that domain and choose its scope.
When `locked` is true, follow the support action returned by `get_status`
instead. The tool confirms commercial identity only; it does not grant user
access or change the login organization.

<Note>
  Before that identity is claimed, `/mcp/v3` can still create, update, or archive
  a test-only advertiser with `save_advertiser` and `sandbox: true`. This exception
  applies only to the operator-identity check: plan selection, current Terms, and
  other readiness blockers still apply. Live advertisers continue to require the
  complete buyer operator identity.
</Note>

Buyer discovery and other new buying operations return HTTP `409` with error
code `BUYER_SETUP_REQUIRED` when the account has no confirmed, non-platform
operator identity. For a missing identity, the exact structured details are
`reason: "missing_operator_identity"`, `readinessCheck:
"operator_identity"`, `setupStep: 1`, and `setupPage: "buyer_setup"`. This is
a correctable account-readiness task, not a seller outage: open **Buyer
Setup**, confirm the operator domain and account scope, then retry the request.

```json theme={null}
{
  "data": null,
  "error": {
    "code": "BUYER_SETUP_REQUIRED",
    "message": "Complete Buyer Setup step 1 by confirming your buyer operator identity before continuing.",
    "details": {
      "reason": "missing_operator_identity",
      "readinessCheck": "operator_identity",
      "setupStep": 1,
      "setupPage": "buyer_setup"
    }
  }
}
```

Apostra never substitutes `interchange.io` for a missing buyer operator.
That would combine unrelated buyers under one seller-side natural-key account.
If a legacy profile explicitly contains that platform domain, the request uses
the same `BUYER_SETUP_REQUIRED` contract with `details.reason:
"platform_operator_not_allowed"`. Replace it with your organization’s operator
domain in **Buyer Setup**.
Changing or confirming the operator affects new discovery and provisioning,
but does not rewrite existing transactions. A historical media buy continues
to use the exact seller account persisted when the buy was created, including
for status, creative re-sync, update, cancellation, and delivery operations.

The same identity gates account linking. A production entry on
`POST /api/v2/buyer/storefront-accounts/sync` (or the
`sync_buyer_storefront_accounts` tool) must name your confirmed operator
domain as `operator`; a different domain returns HTTP `403` with
`ACCESS_DENIED` and `details.reason: "operator_identity_mismatch"`, and a
missing identity returns the `BUYER_SETUP_REQUIRED` contract above. A
sandbox entry (`sandbox: true`) is fenced off from production spend and may
name any operator.

### Billing modes and the business entity payload

Each `sync_accounts` entry names a `billing` mode: `agent` (Interchange
invoices on your behalf; no additional payload needed), `operator`, or
`advertiser` (the storefront invoices your operator or advertiser directly).
`operator` and `advertiser` entries require a `billing_entity` — the AdCP
`BusinessEntity` payload with your legal name and, as applicable, tax/VAT/
registration ids, a postal address, billing contacts, and bank details:

```json theme={null}
{
  "billing": "operator",
  "billing_entity": {
    "legal_name": "Acme Media Ltd",
    "vat_id": "DE123456789",
    "address": {
      "street": "Friedrichstrasse 100",
      "city": "Berlin",
      "postal_code": "10117",
      "country": "DE"
    },
    "contacts": [
      { "role": "billing", "name": "AP Department", "email": "ap@acme.example" }
    ]
  }
}
```

`billing_entity.bank` is write-only: send it to provide payment coordinates,
but it is never echoed back on a `sync_accounts` or `list_accounts` response —
the seller stores it and confirms receipt without returning it.

A storefront only accepts the billing modes it has published support for. An
entry naming an unsupported mode returns HTTP `400` with
`BILLING_NOT_SUPPORTED` and `details.supported_billing` listing the modes the
storefront actually accepts:

```json theme={null}
{
  "data": null,
  "error": {
    "code": "BILLING_NOT_SUPPORTED",
    "message": "billing=operator is not supported by this storefront. Supported: agent.",
    "details": {
      "reason": "billing_not_supported",
      "supported_billing": ["agent"],
      "requested_billing": "operator"
    }
  }
}
```

On the Storefront MCP discovery surface, an explicit opaque `account_id` must
belong to the authenticated buyer on that storefront. A missing buyer grant or
an ID belonging to another buyer returns the structured AdCP error
`ACCOUNT_NOT_FOUND` with `details.reason:
"account_not_authorized_for_buyer"`; it is not reported as a missing
storefront account context. Retrieve an authorized account with
`list_accounts`, or complete the seller's account-linking flow, before retrying.

Buyer Setup returns derived capability verdicts rather than a writable Account
mode. Before Organization proof, plan selection, and Terms, the Account can use
bounded demo and onboarding surfaces. After those steps it can perform real
non-spend work. Spend additionally requires the media-buying product entitlement.
Seller-direct transactions need no Apostra payment method;
Apostra-cleared transactions additionally need the exact route's payment
authority. Account holds block every capability.

Confirming or changing the buyer operator does not change your WorkOS
organization, sign-in, invitations, SSO, account membership, billing company,
advertiser, or brand domain.

## Destination go-live

Every seller or platform then shows only its own remaining requirement:

* A credential-free AdCP seller requires no connection step.
* An official adapter may require a free provider connection, account choice,
  and advertiser mapping.
* A seller can be temporarily unavailable even when your connection is healthy.
* Direct-billed sellers and platforms bill the operator or advertiser and do
  not use an Apostra rate card or payment method for that route.
* A seller cleared by Apostra requires active media pricing supported by
  the current clearing engine and payment authority before live spend. A child
  account automatically uses the media pricing on its billing organization;
  the account-delegation placeholder does not control that inheritance.

The media rate card used to clear a buy is separate from the Organization IU
Rate Card. The IU plan remains an invited staging pilot and is not a production
buyer-readiness requirement.

You can connect destinations, inspect accounts, and view mirrored campaigns
without charge. “Can buy now” means the applicable capability verdict is
allowed and at least one destination’s actual requirements are complete.