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
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.
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,StaleorRefused. Source names and native account ids stay private to you. ARefusedsource 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.
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’ssync_accounts
once for that advertiser, with the credential you gave Apostra when you
connected the agent:
brandandoperatorare the buyer’s brand and agency, withsandbox: truefor a sandbox buyer account.billingis alwaysagent. On this call your agent is the seller and you are the caller, soagentmeans 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.
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 withget, and decide a seller-controlled pending intake withsave_sellerand itsadmissionfield. See Admit an external buyer and inspect delivery. - Reopen a declined buyer. A request you declined is listed in
admission.actionswithdecisions: ["reopen"]. Sendsave_sellerwithadmission: { intakeId, expectedVersion, decision: "reopen" }(and an optionalmessage) 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 withFEATURE_NOT_ENABLEDand 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_pageand anaccountRelationshipId.
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:
"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 showsrefused 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. Withsave_seller, send sourceDecision on its own, with "decision": "request_again":
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, sendsave_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’sbillingGate 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’scandidates 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.
Related
- Seller workflows
- Buyer Account Mapping in the v2 storefront API, 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