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

# Discovering products on a storefront needs an account

> A storefront answers a brief, a refinement or a proposal request only for an account the calling buyer holds. How to set that account up with sync_accounts, what a wholesale browse shows, who can use a proposal, and the errors you get without one.

A storefront on Apostra answers product discovery for one account at a time,
and that account must be one the calling buyer holds. This page is for anyone
who calls a storefront's AdCP `get_products` or `request_proposals` directly,
with their own agent or SDK. If you buy through Apostra's own V3 tools, your
advertiser's account is sent for you.

## What needs an account

| Request | Account |
| - | - |
| `get_products` with `buying_mode` `brief` | Required |
| `get_products` with `buying_mode` `refine` | Required |
| `request_proposals` | Required |
| `get_products` with `buying_mode` `wholesale` | Not needed; read under your account when you send one you hold |

A storefront says so in `get_adcp_capabilities`: `account.required_for_products`
is `true`. A storefront that takes its account from a connected advertising
platform account, such as Meta, does not declare it.

## Set the account up first

Call `sync_accounts` on the storefront for the brand you buy for and the
operator that buys for it.

```json theme={null}
{
  "idempotency_key": "account-setup-0001",
  "accounts": [
    {
      "brand": { "domain": "acme-outdoor.example" },
      "operator": "pinnacle-agency.example",
      "billing": "agent"
    }
  ]
}
```

`billing` is required and must be one of the values the storefront lists in
`account.supported_billing` in `get_adcp_capabilities`; `agent` is the value in
this example. The response names the account in `accounts[].account_id` and its
`status`.
Storefronts approve new accounts by default, so the status is usually `active`
at once. A seller can choose to review accounts first; the status is then
`pending_approval` until the seller approves it, and discovery waits until it
is `active`. While the account waits, its row carries a `setup.message` naming
who is reviewing it. The response is the account's own row, not a task to poll:
call `list_accounts` on the storefront to see when the account becomes
`active`. A `billing` value the storefront does not list fails only that
account's row, with `BILLING_NOT_SUPPORTED`; the other accounts in the request
are still processed.

When the buyer already holds the requested account, `sync_accounts` returns it
as `unchanged` instead of creating another one. A live request also finishes
setup with the storefront's current external sales agent when that agent owns
buyer account decisions. The storefront account stays the same. A dry run only
previews the storefront account and does not call the sales agent.

Send the account on every discovery request:

```json theme={null}
{
  "account": { "account_id": "sf_8c1d0a" },
  "buying_mode": "brief",
  "brief": "Display and video reaching runners in the United States."
}
```

You can send the brand and operator instead of the `account_id`. The
storefront accepts them only as another name for an account you already
synced. A brand and operator you did not sync, or that another buyer synced,
select nothing, and the storefront reads nothing for them.

## Accounts of the Storefront's own organization

A Storefront never holds an account of its own organization for review. When a
buyer account in the same organization as the Storefront asks for an account,
Apostra accepts it at once and records the reason as `account_intake_same_organization_accept`,
whatever the Storefront's account approval policy says and whatever payment
terms the account asks for. Apostra sets these accounts up for you: an
advertiser of a Campaign management account gets its account with its
organization's Storefronts without sending `sync_accounts`. See
[Media partner availability](https://docs.apostra.com/v3/media-partner-availability.md).
A decision the seller already made about a particular account stands, and a
Storefront whose own external sales agent decides its accounts still lets that
agent decide.

## Accounts at a media partner's own sales agents

Some storefronts sell inventory from the media partner's own external sales
agents beside their own. Once the storefront accepts your account, Apostra asks
each of those agents that takes `sync_accounts` for an account for the same
brand and operator. An agent that only lists accounts is not asked: you get the
account it lists for you, if it lists one. You do not send the request.
Products from an agent appear in discovery after the agent accepts the account.
If the agent has not answered yet, or the media partner refused the account, the
storefront's other products still answer and that agent's products are left out.
A refusal is the media partner's decision. Apostra does not ask that agent again
for the same account unless the agent's connection settings change.

## What a wholesale browse shows

A `wholesale` request never needs an account and is never refused for lacking
one. With no account it returns the public catalog, the same for every caller,
with no prices that belong to one account.

Send an account you hold and the browse is read under it. The storefront checks
the account the same way it does for a brief: an `account_id`, or a brand and
operator that name an account you already synced. You then get that account's
catalog:

* Inventory sources your account is not set up for are left out. If the account
  can buy from none of them, the response says so and returns no products.
* A source that keeps its own copy of its catalog for your account serves that
  copy, with its products and prices. A source with no copy for your account
  serves its public catalog.

A brand or operator sent without an account never selects one. An account that
is not an active account you hold on this storefront, whether unknown, held by
another buyer or not yet approved by the seller, is not an error here: the
storefront treats the request as if it named no account and returns the public
catalog. Check the account with `list_accounts` if you expected your own
catalog. To see prices and discounts that apply to your account, discover with
a brief or a refinement under that account.

If you buy through Apostra's V3 tools, `search` with `kind` `wholesale_product`
sends your advertiser's account to each seller, so you see the catalog under
that account without sending anything yourself.

## Discounts follow the account

A storefront applies the seller's discounts and buyer instructions for the
brand and operator of the account you discovered under. A brand or operator in
the request body is never used to pick a discount. A request whose brand does
not match its account is refused with `INVALID_REQUEST`.

## Proposals belong to your buyer account

A proposal a storefront writes for you, in a brief answer or a
`request_proposals` answer, belongs to the buyer account you call as: the one
your credentials sign in to, not the AdCP account in the request. Every AdCP
account you hold can use it. Only your buyer account can finalize it
(`get_products` with `refine: [{ scope: "proposal", action: "finalize" }]`) or
buy from it (`create_media_buy` with `proposal_id`). Another buyer gets the same
answer a proposal id that never existed gets: finalize answers `unable` with
"Proposal id not found for this Seller", and `create_media_buy` answers
`NOT_FOUND` with reason `proposal_not_found`.

Two buyers whose briefs produce the same plan receive different proposal ids,
so neither can use up the other's proposal.

### Proposals from `request_proposals`

A proposal a storefront writes in an AdCP 3.2 `request_proposals` answer is
finalized and bought by its id, the same way as a brief answer's proposal. The
id names one plan on one set of terms: the flight, brand, outcome target and
pricing currency you asked for, and the plan's wording. Change any of the
terms, or let the storefront write the plan with new wording on a later ask,
and it comes back with a new id beside its new `terms_digest`: use the id from
the answer you want to buy.

If only a product's price changed between two answers, with the same plan,
terms and wording, the id stays and the `terms_digest` is new. Read the
`terms_digest` of the answer you are about to buy.

Proposals offered before storefronts started recording whose proposal is
whose, in November 2026, can no longer be finalized or bought. Ask the
storefront for proposals again to get fresh ones.

## When a request is refused

| Situation | Error | What to do |
| - | - | - |
| No account in a brief, refinement or proposal request | `ACCOUNT_SETUP_REQUIRED` | Call `sync_accounts`, then retry with the `account_id`. |
| An `account_id`, or a brand and operator, that is not an account you hold on this storefront | `ACCOUNT_NOT_FOUND` | Check the account with the seller's `list_accounts`, or sync it. |
| An account the seller has not approved, or has suspended | `AUTH_REQUIRED` | Wait for the seller's approval, or ask the seller. |

The storefront checks the account before it reads any catalog or asks any
inventory source, so a refused request returns no products.

A seller who calls its own storefront with its own credential is not a buyer
and needs no buyer account.

## Related

* [Building on Apostra or on AdCP directly](https://docs.apostra.com/v3/apostra-vs-adcp.md)
* [Errors](https://docs.apostra.com/v3/errors.md)


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