> ## 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 Account Mapping Page

> Open the seller's Buyer Account Mapping Page from V3 to review buyer accounts, source coverage and one relationship's account setup case, and decide which account serves a buyer on each source.

Buyer Account Mapping is a Seller Page. It shows each buyer account your
Seller Account has admitted or is reviewing, which buyer organisation owns it,
and whether each of your inventory sources has an account mapped for it. V3
opens it with `open_page`. V3 has no tool that reads or writes its data, so the
review and mapping work happens in the Page itself, by a person.

For why buyers need approving and mapping at all, and why only some of them
wait for you, see [Why you approve and map buyers](https://docs.apostra.com/v3/seller-why-approve-and-map-buyers.md).

## Open the Page

```json theme={null}
{ "page": "buyer_account_mapping" }
```

Opening the Page with no focus returns the consolidated view: operator and
brand relationships and inventory-source coverage.

To open one relationship's **Account setup case** instead, add the relationship
focus. `relationshipId` is the opaque id on an advertiser roster row's
`accountSetupRelationshipId`. `blockedReason` is optional, and it is the
case's blocked reason when you know it, so the case opens directly on it. It is
ignored without `relationshipId`.

```json theme={null}
{
  "page": "buyer_account_mapping",
  "relationshipId": "RELATIONSHIP_ID",
  "blockedReason": "BLOCKED_REASON"
}
```

Only a Seller Account can open the Page. A Buyer Account is refused with a
wrong-account error. `open_page` also accepts `sourceId`, `sourceName` and
`esaId` for other Pages. This Page ignores them.

In the Apostra web app, **Storefront**, then **Buyers**, opens the same Page.
Above it, a buyer picker lists the buyers that trade with you as an Apostra
relationship, and appears only when there is one. Select one of those buyers to
open its media buys, creatives, delivery and **Account**, and choose
**All buyers** to come back to the Page.

## What the Page shows

> [!NOTE]
>
> The complete-account view below is rolled out storefront by storefront. Until
> your Seller Account is enrolled, the Page keeps the relationship-based view.

* **Accounts.** Each buyer account, the verified buyer organisation that owns
  it, and your decision for that account.
* **Existing relationship.** Relationships that predate complete-account
  identity, kept visible and read-only for identity.
* **Source coverage.** For each account, whether every active inventory source
  is `Mapped`, `Not required`, `Not set up`, `Needs account selection`,
  `Stale` or `Refused`. Source names and native account ids stay private to
  you. A `Refused` source also shows what your sales agent answered, when, what
  Apostra asked for and whose move it is, as described under
  [When your sales agent refuses a buyer](https://docs.apostra.com/v3/seller-buyer-account-mapping-page.md#when-your-sales-agent-refuses-a-buyer).
* **Sources.** The last account-listing attempt for each source and whether the
  listing completed.

### Your own sales agents

When your storefront combines several sources and one of them is a sales agent
you connected, such as your ad server's AdCP agent, Apostra sets up each
buyer's account on it when you approve the buyer:

* Apostra maps the buyer to the most specific account the agent lists for it:
  the account for the buyer's agency and brand, then one the agent shares
  across that agency's brands, then one shared across that brand's agencies,
  then the account the agent uses for everything you send (your default).
  Coverage shows `Mapped`.
* If the agent lists several accounts at that level, you choose one. Coverage
  shows `Needs account selection`.
* If it lists none, or cannot list its accounts, Apostra asks the agent for a
  new account. Once the agent's account listing shows it, the buyer is mapped
  to it.

A shared account serves only buyers billed through Apostra. A buyer you bill
directly gets an account of its own requested instead. Several buyers on one
shared account can't be told apart in your ad server for exclusions, frequency
caps or ad review; delivery still reports each buy separately.

On a Google Ad Manager or FreeWheel source run by Apostra's embedded sales
agent, your default is the default advertiser you set for that connection. A buyer billed
through Apostra that you haven't mapped is mapped to it, as if you had chosen
**Use Apostra default** yourself. Choose a specific advertiser for a buyer to
keep them off the default.

Until a buyer's account can buy from at least one of your wholesale sources, a
wholesale product request for that account returns an empty product list with
a message, plus an AdCP `ACCOUNT_SETUP_REQUIRED` entry in its `errors` array
(`recovery: "correctable"`). Buyers on Apostra see that their account with you
needs attention, rather than a search that never finishes.

A sandbox buyer account can only be mapped to a sandbox account, so a test buy
never books on an advertiser that bills. On Apostra's embedded sales agent that
is the agent's own sandbox advertiser. On any other sales agent it is an account
the agent lists as a sandbox account. Apostra refuses any other mapping for a
sandbox buyer account. A sandbox buyer account you leave unmapped still books on the embedded agent's
sandbox advertiser.

When an account Apostra chose for a buyer stops serving them, Apostra maps
them again. That happens when you change your default advertiser, when the
agent stops listing the account, or when the agent narrows the account to
other buyers. If no other account fits, Apostra leaves the mapping as it is
for you to change.

An account you choose yourself always replaces Apostra's choice, and Apostra
never changes it back. If the agent stops listing such an account, or you
change the default advertiser it follows, coverage shows `Stale` until you
choose another.

#### What Apostra asks your agent for

When you approve a buyer and your agent lists no account Apostra can map for
it, or cannot list its accounts, Apostra calls your agent's `sync_accounts`
once for that advertiser, with the credential you gave Apostra when you
connected the agent:

* `brand` and `operator` are the buyer's brand and agency, with `sandbox: true`
  for a sandbox buyer account.
* `billing` is always `agent`. On this call your agent is the seller and you
  are the caller, so `agent` means your agent invoices you under the contract
  you already have with it. It never means your agent bills the buyer, and it
  does not change with how the buyer pays you.
* No payment terms are sent.

Your agent should accept this request on your credential for any brand and
agency you approve, in sandbox and in production. It should return one account
for each brand, agency and environment, and the same account each time it is
asked again. An active account is mapped straight away. A pending one is
mapped once your agent reports it active.

If your agent refuses, Apostra records the refusal with your agent's reason. It
does not retry with a different `billing` value, even when your agent suggests
one such as `operator`, because that would ask your agent to invoice the
buyer's agency. `BILLING_NOT_PERMITTED_FOR_AGENT` means your agent is not set
up to accept agent billing on the credential you gave Apostra. Change that in
your agent's setup. You don't need to contact Apostra: once the account check
below passes on that inventory source after the refusal, Apostra sends each
request your agent refused with `BILLING_NOT_PERMITTED_FOR_AGENT` or
`BILLING_NOT_SUPPORTED` again. If your agent refuses it again, Apostra waits
for a check that passes after that refusal before asking once more. Apostra
does not ask again after a refusal for any other reason.

Apostra checks this on each of your agent inventory sources, daily until it
passes and then weekly. A new agent inventory source stays pending until its
check passes with the credential it uses now, so it never goes live unable to
take your buyers' accounts. If you reconnect the agent with a different
credential, Apostra checks it again before the source can go live. A source
that is already live keeps running, and a failed check shows on its health.

A storefront that sells only through one connected agent works differently.
There the agent is the seller to the buyer: it decides buyer accounts itself,
and the request it receives carries the buyer's own billing choice.

The Account setup case for one relationship shows one of these neutral
statuses:

| Status | What it means |
| - | - |
| Needs setup, waiting on you | The case is blocked on your side. Provide or confirm the setup details. |
| Waiting on buyer | A request for information is with the buyer. The buyer needs to respond. |
| Awaiting billing | A direct-billed grant is waiting on a ready-to-invoice assertion for its billing entity. |

Inside the Page, a person can also review pending buyer access, choose or
confirm the source account for each source, download mapping CSV files, ask
a buyer for information and confirm or
withdraw that request, and assert or revoke billing readiness for a
direct-billed account.

## What V3 covers and what it does not

V3's own contract covers opening the Page, with or without a relationship
focus, and the summary read behind the consolidated view.

V3 reads what the Page shows about a buyer (see
[Read a buyer's requests, billing and account key](https://docs.apostra.com/v3/seller-buyer-account-mapping-page.md#read-a-buyers-requests-billing-and-account-key)),
and writes most of the other jobs in the list above (see
[Ask a buyer for information](https://docs.apostra.com/v3/seller-buyer-account-mapping-page.md#ask-a-buyer-for-information)
and
[Assert that a buyer is billable](https://docs.apostra.com/v3/seller-buyer-account-mapping-page.md#assert-that-a-buyer-is-billable)).
An agent cannot download mapping files through V3. When a job needs
that, open the Page, show the person the relationship focus and let them decide
there.

Four jobs around the Page have a V3 owner today:

* **Admit or decline an external buyer.** Read the roster with
  `search({ "kind": "account_relationship" })`, read one relationship with `get`,
  and decide a seller-controlled pending intake with `save_seller` and its
  `admission` field. See
  [Admit an external buyer and inspect delivery](https://docs.apostra.com/v2/setup/v3/seller-workflows.md#admit-an-external-buyer-and-inspect-delivery).
* **Reopen a declined buyer.** A request you declined is listed in
  `admission.actions` with `decisions: ["reopen"]`. Send `save_seller` with
  `admission: { intakeId, expectedVersion, decision: "reopen" }` (and an
  optional `message`) to return it to pending review, then decide it again. The
  request must be one you control, not an external agent. Reopening is available
  while the Seller Account still uses retained relationships; on a company-scoped
  account the service refuses it with `FEATURE_NOT_ENABLED` and no declined
  request is listed.
* **Decide which account serves a buyer on each source.** See
  [Decide which account serves each source](https://docs.apostra.com/v3/seller-buyer-account-mapping-page.md#decide-which-account-serves-each-source) below.
* **Inspect an admitted buyer's delivery.** Open the relationship-scoped Media
  Buys Page with `open_media_buys_page` and an `accountRelationshipId`.

Admission decides whether a buyer gets in. Source coverage decides which of
your sources can serve that buyer, and billing readiness decides whether a
direct-billed buyer can place orders. A buyer can be admitted and still show
`Not set up` coverage or `Awaiting billing`. Re-read the relationship rather
than assuming it is eligible.

### Decide which account serves each source

Once you admit a buyer, each of your inventory sources that can hold a buyer
account needs a decision before it can serve that buyer. Either the buyer is
served by a specific account on that source (`bound`, shown as `Mapped`), or
the source needs no account for it (`not_required`, shown as `Not required`).
Until you decide, the source is withheld from the buyer: its products are not
shown to them and their buys do not route there.

Some sources cannot hold a buyer account:

* a source built from modules none of which declares a buyer account (today
  only CitrusAd modules declare one);
* a source run by Apostra's embedded sales agent on an ad server other than
  Google Ad Manager or FreeWheel; and
* a source linked from another storefront.

`not_required` is the only decision such a source can take, so you don't need
to record anything: it serves every buyer you admit as `not_required` and shows
as `Not required`. That includes buyers you admitted before this rule existed.
A source with a module that declares a buyer account, such as CitrusAd, is not
one of these, even while it is part-way through setup or one of its modules is
paused. It waits for your decision like any source that holds buyer accounts.

A source run by Apostra's embedded sales agent on another ad server serves a
buyer only on a retained relationship whose buyer is billed through Apostra. It
does not serve a buyer you bill directly, or a buyer on a complete account (one
with an `accountKey`), today. It still shows `Not required` for those buyers.

To keep an admitted buyer off such a source, decline or revoke that buyer, or
turn the source off by setting its `status` to `DISABLED` with
`save_inventory_source`. A disabled source stops selling to every buyer.
Leaving the source undecided does not withhold it, and there is no decision
that withholds one source from one buyer. Restricting a product to named buyer
accounts is planned but not available yet.

`get({ "kind": "account_relationship", "id": ... })` returns `sources`, one
entry per inventory source (`search` leaves them out, so find the relationship
with `search` first and then read it with `get`):

| Field | Meaning |
| - | - |
| `inventorySourceKey` | The source the entry is about. |
| `state` | `bound`, `not_required` (recorded, or a source that cannot hold a buyer account), `missing` (no decision yet on any other source), `ambiguous` (several accounts match and you must choose one), `stale` (the mapped account is no longer listed by the source) or `refused` (your own sales agent refused the account request Apostra sent for this buyer; see [When your sales agent refuses a buyer](https://docs.apostra.com/v3/seller-buyer-account-mapping-page.md#when-your-sales-agent-refuses-a-buyer)). |
| `refusal` | Present when `state` is `refused`: what Apostra asked for, your agent's answer, when it answered and whose move it is. |
| `sourceExternalAccountId` | The source's own account mapped to this buyer, or `null`. |
| `expectedVersion` | Send this with your decision. It is `0` before the first decision. |
| `lastSeenAt` | When the source last observed the mapped account. Left out when no account is mapped or the source has not observed it. |
| `candidateCount`, `candidates` | Accounts on the source that match the buyer's operator, brand and sandbox setting. Up to five are listed, each with its `displayLabel` and `lastSeenAt` (when the source last observed it); the rest are on the Page. |

Record a decision with `save_seller` and its `sourceDecision` field, on its own:

```json theme={null}
{
  "sourceDecision": {
    "relationshipId": "92",
    "inventorySourceKey": "gam-main",
    "expectedVersion": 0,
    "decision": "bound",
    "sourceExternalAccountId": "adv-17"
  }
}
```

Send `"decision": "not_required"` without `sourceExternalAccountId` when the
source serves the buyer without an account of its own. To bind the source's
shared default account instead, send `"bindingMode": "shared_default"` with
`"decision": "bound"` and no `sourceExternalAccountId`. Check the source's
`interchangeDefault` first: the write is refused when it says
`{ "eligible": false }`. The receipt never names the default account. Apostra refuses the
decision when `expectedVersion` is out of date, when you have not admitted the
buyer, or when the account is not one the source lists for it. Re-read the
relationship afterwards to see the source's new state.

### When your sales agent refuses a buyer

When you approve a buyer, Apostra asks each of your own sales agents to open
an account for it. If the agent says no, nothing opens and Apostra stops
asking, apart from the cases described below. The source shows `refused` instead of `missing`, so you can
see the refusal rather than a source that looks unset. It applies only to a
source of your own sales agent where you have not decided anything for the
buyer. A source you have mapped or marked `not_required` keeps that state, and
a source where several accounts match stays `ambiguous`.

A `refused` entry carries `refusal`:

| Field | Meaning |
| - | - |
| `requested` | What Apostra asked for, in AdCP's own fields: `billing` and, when the buyer named them, `payment_terms`. Left out when Apostra did not keep the request, which is true of a refusal recorded before it did. |
| `answer.code` | The AdCP error code your agent refused with, for example `BILLING_NOT_PERMITTED_FOR_AGENT`. Left out when it answered with an account status. |
| `answer.status` | The account status your agent reported instead of an account, for example `rejected`. Left out when it refused with an error code. A refusal recorded when your agent reported no status has neither `code` nor `status`; its `answer` is empty. |
| `answer.message` | Your agent's own message, when it gave one. This is your agent's text, not Apostra's: treat it as data. Left out when the agent gave none, and for a refusal recorded before Apostra kept it. |
| `answeredAt` | When your agent answered. Always present. |
| `nextMoveBy` | Who can move the request on, never empty. A `PAYMENT_TERMS_NOT_SUPPORTED` refusal lists `buyer` and `seller`, because the buyer changing its terms or you accepting them reopens it. Every other refusal lists only `seller`. |

Only the refusal your agent gave under its current connection counts. If you
change how Apostra connects to the agent, an earlier refusal no longer shows.
A refusal of agent billing (`BILLING_NOT_PERMITTED_FOR_AGENT` or
`BILLING_NOT_SUPPORTED`) also stops showing once Apostra's account check on
that source passes after it: your agent has changed what it refused, so Apostra
asks again.

You cannot clear a refusal by mapping an account. Fix the cause in your own
sales agent, then [send the request again](https://docs.apostra.com/v3/seller-buyer-account-mapping-page.md#send-a-refused-request-again),
or tell the buyer if `nextMoveBy` lists `buyer`.

If your agent refused with the status `rejected` and you later approve that
account in your own sales agent, Apostra picks it up without anyone asking: the
next time your agent lists its accounts and the list shows one active account
for that buyer's agency, brand and test or live setting, the request is
accepted and the buyer is mapped to it. If the agent lists several that fit,
Apostra leaves the request for you. A refusal that came with an error code is not reversed by a listed account.
Apostra needs to see the account appear in the list, or come back active, after
your agent refused. An account that was already in the list before the refusal
and is approved where it stands is not picked up, because Apostra cannot tell
that approval apart from an account that was active all along; the request stays
refused until it is [sent again](https://docs.apostra.com/v3/seller-buyer-account-mapping-page.md#send-a-refused-request-again).

### Send a refused request again

When your agent can accept the request, for example after you change its setup,
or because you decided to accept a buyer it rejected, send the request again.
On the Buyers Page, press **Send again** on the refused source. With
`save_seller`, send `sourceDecision` on its own, with `"decision": "request_again"`:

```json theme={null}
{
  "sourceDecision": {
    "relationshipId": "92",
    "inventorySourceKey": "triton-agent",
    "expectedVersion": 0,
    "decision": "request_again"
  }
}
```

Send the source's `expectedVersion` (it is `0` while you have made no decision
for the source) and no account. Apostra puts the same request back in its queue
and sends it to your agent the way it sends any account request: under the
buyer's identity and the payment terms the buyer has chosen at that moment. It
never changes the buyer's billing or payment terms, even when your agent
suggested other ones. The receipt says the source is `queued`. Until your agent
answers, the source shows as not yet set up rather than `refused`. If the agent
accepts, the account is mapped when it is active. If it refuses again, the
source shows `refused` again with the new answer.

Apostra refuses the request when:

| Refusal | Why |
| - | - |
| `CONFLICT` | The source is not `refused` when you send. Your agent may have accepted since you read it, you may have decided the source, or the request is already queued. Re-read the relationship. |
| `CONFLICT` | `expectedVersion` is out of date. Re-read the relationship. |
| `NOT_FOUND` | You have not admitted the buyer, or the relationship has no such source. |
| `RATE_LIMITED` | You sent the same request again less than an hour ago. `details.retryAt` says when you can send it again. |

A request can be sent again once an hour. Sending it queues it, so it can be
sent again only after your agent has refused it again, and an agent that keeps
refusing cannot be asked in a loop. Send it again after you have changed
something: the same request to an agent that has not changed collects the same
refusal.

### Read a buyer's requests, billing and account key

`search({ "kind": "account_relationship" })` returns one row per buyer, and
`get` returns the same row with more detail. Both carry:

| Field | Meaning |
| - | - |
| `verifiedBuyerOwner` | The buyer's verified organisation name. Absent on a retained relationship row. |
| `billingGate` | Present only when direct billing needs a ready-to-invoice assertion. `status` is `pending` (no assertion yet), `ready` or `revoked`. |
| `admission.actions` | One entry for every open request, and one for each request you declined that you can reopen (`get` only, up to five, newest first). `decisions` is empty when you cannot decide it (an external agent or the buyer owns the next step) and is `["reopen"]` for a declined request. `authority` is `seller`, `external_agent` or `account_input`, and `billingReady` says whether the billing it asks for is ready. |
| `openProposalCount`, `mtdSpend` | Proposals and month-to-date spend, on retained relationship rows only. |

`get` adds:

| Field | Meaning |
| - | - |
| `accountKey` | The buyer account's AdCP key: `brand` (`domain`, `brand_id`, `countries`), `operator`, `operator_unit`, `currency`, `timezone` and `sandbox`. Absent on a retained relationship row. |
| `grants` | The buyer's grants, each with its `status`, the `billing` party and a `count`. |
| `billingGate.billing_entity`, `billingGate.assertionId` | The legal entity a ready-to-invoice assertion must repeat exactly, and the assertion's id while the gate is `ready`. |
| `billingReadiness.assertions` | The ready-to-invoice assertions that are active now. |
| `admission.actions[].case` | For a request you can decide: the policy outcome, whether the buyer matched your CRM, who the case is waiting on (`blockedOn`) and the pending information request, with its `launchUrl` while it is live. |
| `sources[].bindingMode` | `dedicated` or `shared_default`, for a bound source. |
| `sources[].interchangeDefault` | `{ "eligible": true }`, or `{ "eligible": false, "reason": ... }` when the source's shared default account cannot be bound for this buyer. |

The first page of a `search` also returns `sources`, the inventory sources that
take account mappings with how fresh each roster is, `totals.buyersCount`, and
`retainedTotal` when you still have retained relationship rows. Those rows have
no account key and are listed after all the others; page through them with the
`nextCursor` the search returns.

### Ask a buyer for information

When a pending request needs something from the buyer, such as a credit form,
send `save_seller` with `informationRequest`, on its own:

```json theme={null}
{
  "informationRequest": {
    "action": "request",
    "intakeId": "91",
    "setup": {
      "message": "Please send your credit form.",
      "url": "https://forms.example/credit",
      "expires_at": "2026-12-01T00:00:00Z"
    }
  }
}
```

`setup` is AdCP's account setup object. The `message` is plain text of 1 to
2,000 characters with no markup. `url` is your own HTTPS process link and may
not carry credentials. `expires_at` is required here, in the future and within
365 days. The result carries the `setup` you sent, the `launchUrl` to hand to
the buyer and the `requestId`. Until the buyer responds
or the request lapses, the case is waiting on the buyer, and a second request
for the same intake is refused.

Once the buyer has done it, send `{ "action": "confirm", "requestId": ... }`.
To drop your own request without deciding the intake, send
`{ "action": "withdraw", "requestId": ..., "reason": ... }`; the intake stays
open on your queue. Read the `requestId` from
`admission.actions[].case.informationRequest` on `get`, which also carries the
live request's `setup` (`message` and `expires_at`).

### Assert that a buyer is billable

A direct-billed buyer (billed through the operator or the advertiser) cannot
place orders until you assert that the billing party can be invoiced. The
buyer's `billingGate` shows where that stands, and its `billing_entity` is the
legal entity the assertion must repeat exactly, including every identifier it
shows. Send `save_seller` with `readyToInvoice`, on its own:

```json theme={null}
{
  "readyToInvoice": {
    "action": "assert",
    "relationshipId": "92",
    "billing": "operator",
    "billing_entity": { "legal_name": "Buyer GmbH", "vat_id": "DE123456789" },
    "authority": "finance_staff",
    "evidence": { "reference": "INV-ACC-1" },
    "validUntil": "2027-06-30T00:00:00Z"
  }
}
```

`billing` is `operator` or `advertiser`. `authority` is `crm`, `erp`,
`finance_staff` or `external_workflow`. `evidence` is a short reference or note,
never a document. A new assertion for the same party supersedes the old one.
To withdraw it, send `{ "action": "revoke", "assertionId": ..., "reason": ... }`:
grants billed to that party return to payment required and direct-billed buying
stops, while buys already committed are not affected. The service refuses both
when the storefront's connected sales agent manages the buyer accounts.

### Find the right account on a source

A buyer's `candidates` are the accounts on a source that match its operator,
brand and sandbox setting exactly, and up to five are listed. When the account
you want is not among them, search the source's full roster:

```json theme={null}
{ "kind": "source_account", "sourceId": "gam-main", "query": "acme" }
```

`sourceId` is a source's `inventorySourceKey` (the first page of an
`account_relationship` search lists the sources that take account mappings).
Each row is an account the source has reported: `account_id` is the value to
send as `sourceExternalAccountId`, `name` is its label, `brand.domain`,
`operator` and `sandbox` are what the source observed, and `nativeStatus` is the
source's own status. A page holds up to 100 accounts, and the result gives the
source's roster freshness (`source.reconciliation`) and a `nextCursor`.

If the account was created on the source after its last listing, ask the source
to list again with `refresh_inventory_source_health` and `"scope": "accounts"`.
The result says whether the listing was `complete`, how many accounts it listed,
observed and archived, and whether it was truncated. An incomplete listing keeps
the last complete roster. The default `scope`, `health`, is the source health
check as before.

## Related

* [Seller workflows](https://docs.apostra.com/v2/setup/v3/seller-workflows.md)
* [Buyer Account Mapping in the v2 storefront API](https://docs.apostra.com/v2/storefront/buyer-account-mapping.md),
  which documents the account identity model, billing paths and CSV format in
  detail. It describes the v2 storefront API, which is deprecated.
* [Source diagnostics Page](https://docs.apostra.com/v3/seller-source-diagnostics-page.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.