Skip to main content
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.

Open the Page

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.
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

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.
  • 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: 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), and writes most of the other jobs in the list above (see Ask a buyer for information and 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.
  • 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 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): Record a decision with save_seller and its sourceDecision field, on its own:
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: 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, 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.

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":
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: 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: get adds: 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:
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:
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:
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.