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

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