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

# How your discovery targeting reaches sellers

> Which parts of a brief's structured targeting a storefront passes on to the sellers behind it, when a seller that cannot honour it is left out of the answer, why a seller's pricing and forecasts may not reflect targeting it was not sent, and how discovery names the requested publishers no seller on Apostra carries.

When you ask a storefront for products, you can send structured targeting
alongside the brief: AdCP's `targeting_overlay` (for example the countries you
want, through `geo_countries`) and `required_overlay_support` (the targeting
you need to be able to set later). A storefront that resells an outside seller
passes that targeting on to the seller, so the seller can price and forecast
for it. AdCP asks sellers to scope a product's `forecast` to the concrete
targeting they receive in discovery.

## What each seller receives

| Seller | `targeting_overlay` | `required_overlay_support` |
| - | - | - |
| Speaks AdCP 3.2 or later | The fields it can honour (below) | Sent unchanged |
| Speaks AdCP 3.1 or earlier | Not sent: these versions have no such field | Not sent |

For a seller on AdCP 3.2 or later, each `targeting_overlay` field is handled
by how the seller declares it:

* **Fields a seller declares for its whole account** in its capabilities
  (`media_buy.execution.targeting`), such as countries, regions, metros,
  postal areas, places, language, keywords and property lists: sent when the
  seller declares that field and supports the values you asked for. A seller
  that declares its targeting but leaves out a field you sent, or does not
  support its values, cannot honour your targeting. Its products are left out
  of the answer (see below). For example, a seller that lists only
  `nielsen_dma` metros is left out when you ask for a metro in another system.
* **Fields a seller declares per product**, such as device type, audiences,
  signals, dayparts and frequency caps: always sent. AdCP has the seller leave
  out or adjust a product that cannot honour them, not refuse the request.
* **Demographics, including age:** not sent. Outside sellers read age from the
  brief text.

`required_overlay_support` is sent unchanged because dropping part of it would
return products you said you could not use.

A property list sent as a discovery filter (`filters.property_list`) reaches
only a seller that declares it can filter by property list.

## Sellers left out of the answer

Your targeting is a requirement on the answer, not only a field to pass on.
When a seller on AdCP 3.2 or later declares it cannot honour a field you sent
for its whole account, as described above, the storefront does not call that
seller and returns none of its products, live or cached, because their pricing
and forecasts could not reflect your targeting.

The response says which sellers were left out and why. Each one adds an entry
to the response's `errors` array, one per field it cannot honour:

```json theme={null}
{
  "code": "UNSUPPORTED_FEATURE",
  "message": "Seller A was left out of these results because it does not support targeting_overlay.geo_metros as requested.",
  "field": "targeting_overlay.geo_metros",
  "recovery": "correctable",
  "suggestion": "Remove or change targeting_overlay.geo_metros to see products from Seller A.",
  "details": { "unsupported_dimension": "geo_metros" }
}
```

These entries do not fail the request: products from the other sellers are
returned as usual. If every seller is left out, the answer has no products and
the entries say why. To see a left-out seller's products, remove or broaden
the field named in `field`.

A seller sees how often it was left out, and for which fields, on its Agent
page. [Declare the targeting you honour](https://docs.apostra.com/v3/agent-requirements.md#declare-the-targeting-you-honour)
explains how a seller declares its targeting.

A seller is kept when we cannot tell whether it can honour your targeting: a
seller on AdCP 3.1 or earlier, which cannot receive it, and a seller that
declares no targeting at all. Their products are returned without their
forecasts, as the next section explains. Fields a seller declares
per product, and demographics, never leave a seller out.

## What this means for forecasts

AdCP asks a seller to scope a product's `forecast` to the targeting it
receives in discovery. A forecast built without your targeting describes the
seller's default scope, usually its whole footprint, so it can overstate what
is available to you many times over.

When you send `targeting_overlay` with any field other than age, the
storefront leaves `forecast` off every product whose forecast was not built
with that targeting:

* products from a seller that was not sent all of it, such as a seller on AdCP
  3.1 or earlier, or one that declares no targeting;
* products served from the storefront's cached copy of a seller's catalog,
  which is fetched without any buyer's targeting;
* products from a storefront that resells another storefront, which does not
  receive your targeting.

Products from a seller that received all of it keep their forecast.

When any forecast is left off, the response says so in AdCP's `incomplete`
field, naming the sellers, and in its text summary:

```json theme={null}
{
  "incomplete": [
    {
      "scope": "forecast",
      "description": "Forecasts are left off products from Seller B: these sellers did not receive your targeting for this request, so their forecasts would describe a broader scope than you asked for."
    }
  ]
}
```

The products themselves are returned as usual. Age does not count:
storefronts match age on each product's declared age targeting. Other
demographics, such as gender, do count, because outside sellers are not sent
them.
Pricing is not changed: a seller that prices by targeting still shows its
default price.

A seller on AdCP 3.1 or earlier can still narrow which products it returns
from `filters.countries` and the other product filters, but it cannot scope a
forecast to them.

Exclusion lists, such as a list of domains to avoid, are not discovery
targeting. AdCP applies them when the media buy is booked, through
`targeting_overlay.property_list_exclude` on the buy.

## Publishers no seller on Apostra carries

When the advertiser has an inclusion property list, `request_proposals` also
tells you which publishers on that list no seller on Apostra carries, and which
only a reseller carries. The completed response's `inclusionPropertyList`
summary gains `missingPublishers`, with `missingPublishersTotal` and
`missingPublishersTruncated`. They are present only when there is at least one
publisher to list. The list holds at most 25 entries; `missingPublishersTotal`
is the full count.

Each entry names the requested `domain` and a `reason`:

| `reason` | Meaning |
| - | - |
| `no_seller` | No seller you can see on Apostra carries the domain. |
| `reseller_only` | Every seller you can see that carries the domain resells it: it declares that it sells third-party inventory, and the domain is not its own operator domain. The entry also has `resellers` (at most 3, each a `sellerAccountId` and a `sellerName`) and `resellersTotal`. |

A reseller is not necessarily the right seller for a publisher. A network or
exchange may carry a publisher's inventory without the publisher's terms,
formats or prices, so `reseller_only` tells you that any products you see for
the domain come only through a reseller.

How the list is decided:

* **What "carries" means.** A seller carries a domain when it is one of the
  seller's publisher domains or its operator domain. Domains are compared
  exactly after lower-casing and removing a leading `www.`. A subdomain is never
  matched to its parent, so `news.example.com` does not stand in for
  `example.com`.
* **Which sellers count.** Only the sellers your Marketplace shows: listed, not
  archived and not opted out of the Marketplace. A seller still waiting for listing
  review does not count, so the list never reveals a seller you could not find
  yourself. A seller counts whether or not this round asked it, whether it can
  take bookings now, and whether it is turned on for the advertiser.
  `skippedSellers` and the per-seller outcomes explain those cases.
* **When a domain is listed.** A domain is listed when no seller carries it as
  the publisher's own. A reseller that returned products for the domain does not
  remove it from the list. A domain whose own seller is on Apostra is never
  listed, even when that seller returned nothing for it in this round. The
  per-seller entries explain that.
* **When it is decided.** The list is worked out once, when the round is
  created, and kept with the round. Asking again with the same `idempotencyKey`
  returns the same list. A round created before this field existed has none.

Discovery records no request and contacts no publisher. If you want a listed
publisher on Apostra, you can invite it to join and record a supply request for
it with `save_ask` (`type: "supply"`, the domain as `subject`, a channel, and
the `countries` you want to buy in).
the Apostra assistant offers to record one for each listed domain and records it only when you
say yes.

## Signal prices in proposals

When the seller's signal prices can be verified, a proposal shows the media
price separately from the price of its forecast audience signals. Signals in
the same pricing group may be charged once at the highest listed price. For
example, €3.75 media and a €0.50 age group total €4.25 per thousand impressions.
Some guaranteed offers require the quoted group; if the seller cannot book
the product without it, the group cannot be removed. Existing bookings retain
their agreed price.

## Related

* [Discovering products on a storefront needs an account](https://docs.apostra.com/v3/storefront-discovery-needs-an-account.md)
* [Build an agent](https://docs.apostra.com/v3/build-an-agent.md): how to check each package's targeting after you book
* [Apostra and AdCP](https://docs.apostra.com/v3/apostra-vs-adcp.md)


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