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

# Create and manage seller products

> Create, change, archive and delete a wholesale product on an ad-server source with save_wholesale_product, and check whether buyers can see it.

A **wholesale product** is what you author from synced ad-server inventory so
buyers can discover and buy it. In V3 you create and manage one with
`save_wholesale_product` and read it with `search` and `get`. The field-level
rules for prices, formats, channels and audience declarations are in
[Create products from ad-server inventory](https://docs.apostra.com/v2/storefront/inventory-sources/create-products.md).
This page is the V3 workflow.

## Which sources hold products you can author

You author products only on a source Apostra manages for you, which means an
ad-server-backed source. Pass its `sourceId`, as returned by
`search({ "kind": "inventory_source" })`, on every call. A source that does not
hold products you author refuses the write with `refused:
"not_our_system_of_record"` and says why:

| Source | Why it refuses |
| - | - |
| Third-party sales agent | Its products live in that agent. Apostra reads them and does not write them. Change them in the agent. You can still list them: see [Read a third-party sales agent's products](https://docs.apostra.com/v3/seller-product-creation.md#read-a-third-party-sales-agents-products). |
| Modular source | Its products come from the avails file you upload. Upload a new file to change what it offers. See [Modular source Pages](https://docs.apostra.com/v3/seller-modular-source-pages.md). |
| Linked storefront | Its products belong to the other Seller and are resolved when a buyer asks. |

A source whose ad server is disconnected is refused with `source_disconnected`.
Reconnect it first. A source still being set up upstream is refused with
`source_not_provisioned`. Read it with `get` and `include: ["diagnostics"]`,
then retry.

## Create a product

A create has no `id`. It needs `name`, `channels` and `inventory` with an
`inventory.execution` block. When you send `pricingOptions` you also send
`deliveryType`.

```json theme={null}
{
  "sourceId": "SOURCE_ID",
  "name": "Homepage takeover",
  "channels": ["display"],
  "inventory": {
    "execution": {
      "adapter": "google_ad_manager",
      "selectors": [{ "selector_type": "ad_unit", "external_id": "AD_UNIT_ID" }]
    }
  },
  "deliveryType": "guaranteed",
  "pricingOptions": [
    { "pricing_model": "cpm", "currency": "USD", "fixed_price": 12.5 }
  ]
}
```

* `channels` are AdCP media channels. The tool refuses `audio` and `video`, an
  empty list, and more distinct channels than a product can hold. The Inventory
  Selector asks you to choose the channels and preselects none, and Components
  asks for them when you edit a product that was saved with none.
* `inventory` has two parts. `inventory.execution` is how the ad server runs the
  product, and buyers never see it. `inventory.publisher_properties` is the
  publisher scope buyers see, as AdCP publisher selectors (`publisher_domain`,
  `selection_type` and, for `by_id` or `by_tag`, `property_ids` or
  `property_tags`). Both are closed: the tool refuses a field it does not list.
* `inventory.execution` needs an `adapter` (the source's ad-server adapter) and
  carries the `selectors` to sell and any `format_bindings`. A selector is a
  `selector_type`, an `external_id` and optionally a `name` and `options`. A
  format binding is a `format_option_id` and optionally an `adapter_config`. The
  tool refuses a create without `inventory.execution` and its `adapter` before
  it contacts the source, and names the field in the refusal. To find the
  selector ids, formats and publisher properties a source offers, see
  [Browse what an ad-server source offers](https://docs.apostra.com/v3/seller-browse-ad-server-source.md).
* A selector's `options` and a format binding's `adapter_config` depend on the
  ad server, so each is a list of `{ "key", "value" }` entries, one per setting.
  `key` is the path to the setting: dotted names for nested objects, `[n]` for a
  list item, and `["a.b"]` for a name that holds a dot, a bracket or a space.
  `value` is a string, a number, a boolean, a list of strings, `null` or an empty
  object `{}`. These entries:

  ```json theme={null}
  [
    { "key": "creative_placeholders[0].slot_id", "value": "leaderboard" },
    { "key": "roadblocking", "value": "as_many_as_possible" }
  ]
  ```

  send `{ "creative_placeholders": [{ "slot_id": "leaderboard" }], "roadblocking": "as_many_as_possible" }`
  to the source. A key listed twice, a key that is both a value and the parent
  of another, or a gap in a list is refused.
* `get` and `search` return `inventory` in the shape a save takes:
  `execution` under the names above, each `options` and `adapter_config` as
  entries, and `publisher_properties` as AdCP selectors. To change one setting,
  read the product, edit its `inventory`, and send the whole `inventory` back.
  Setting names come back exactly as stored.
* A change may leave `execution` out (or send it as `null`) and keeps the stored
  one. An `execution` it does send needs an `adapter` and replaces the stored
  block whole, so any `selectors` or `format_bindings` it leaves out are no
  longer on the product: send the complete block you want. `publisher_properties`
  is replaced whole the same way, and `[]` clears it.
* The older open `inventory`, where `options` and `adapter_config` are objects
  and any other key is passed through, still works for now. Send entries
  instead: the open form will be removed.
* `status` is `draft`, `active` or `archived`. A `draft` is hidden from buyers.
  The result states the status the source gave the product. Save
  `status: "active"` when the product is ready.
* `fixed_price` can be `0`. A `$0` fixed price is a complete price that buyers
  can see and book, for donated, house or added-value inventory. It is not the
  same as leaving `fixed_price` out: an option with no `fixed_price` is an
  auction and keeps listing with no floor and no price guidance. A `fixed_price`
  cannot be negative. The `fixed_price` still has to be in your settlement
  currency to list. A `$0` price makes the product visible and bookable at that
  price. A buyer books it with a `$0` budget and states the delivery owed as an
  impressions goal, which reaches you as the package's `impressions`.
* `min_spend_per_package` is AdCP's least spend per package for a price option,
  in the option's own currency. It is a number of 0 or more, and it works on a
  fixed or an auction option. Booking refuses a buy below it. A read returns it
  as a number.
* `floor_price` is AdCP's auction floor, in the option's own currency. It is a
  number of 0 or more, and it belongs on an auction option: the tool refuses it
  beside a `fixed_price`, because AdCP makes the two exclusive. A floor of `0`
  on a `cpm` auction means no floor is declared. V3 sends the floor to the
  managed sales agent unchanged and never writes it into `price_guidance`,
  which AdCP keeps for the percentiles the source derives. After a write that
  carries a floor, the tool reads the product back. If the source kept a
  different floor, the call is refused with an error that names the option, the
  floor you sent and the floor the source kept. The write is not undone, so the
  product holds what the source kept, and the error says so: it names the
  product id, carries `details.outcome` of `saved_floor_unconfirmed`, and
  sets `recovery` to `terminal`, which outranks its `SERVICE_UNAVAILABLE` code.
  Do not send the call again, which would create the product a second time. A read
  that cannot be made is refused the same way, never reported as saved.
* A create is validated against the source before anything is written. A
  blocking finding stops the save and the result carries `saved: false`,
  `refused: "validation_failed"` and the findings as `errors`, each with a
  `code`, a `message` and a `field` when the source named one. Advisory
  findings do not block the save and come back as `warnings`.

### Check a create without saving it

Add `dryRun: true` to a create to validate it and write nothing. A valid
product returns `saved: false`, `dryRun: true` and `valid: true`. A change
cannot be dry-run, because a change carries only the fields you named and the
source validates complete products.

On a Google Ad Manager source, a valid dry run also returns
`lineItemTargeting`: the targeting every line item booked from the product
carries, exactly as Google Ad Manager will receive it. Use it to confirm a
product's [fixed targeting](https://docs.apostra.com/v3/seller-product-creation.md#seller-fixed-and-buyer-chosen-targeting)
before you make the product `active`.

## Change a product

Pass the product `id` and only the fields you want to change. Every field you
omit keeps its stored value.

```json theme={null}
{
  "sourceId": "SOURCE_ID",
  "id": "PRODUCT_ID",
  "deliveryType": "guaranteed",
  "pricingOptions": [
    { "pricing_model": "cpm", "currency": "USD", "fixed_price": 14 }
  ]
}
```

* `pricingOptions` are replaced whole. Send every price you want to keep. Any
  [AdCP pricing model](https://docs.apostra.com/v3/seller-product-creation.md#price-a-product-in-any-adcp-pricing-model)
  the source sells works; the rules below apply to each model alike.
* A price change keeps the minimum spend per package and the auction floor the
  product already has. The tool reads the stored options and carries these terms
  over to the one new option with the same `pricing_model` and `currency`. A
  `floor_price` or `min_spend_per_package` you state on the option replaces the
  stored one. The floor stays only while that option is still an auction: a
  `fixed_price` replaces it, and the minimum spend stays. If a stored floor or
  minimum spend has no single matching option in your list and you did not
  state it on every option with that model and currency, for example you change
  the currency, drop the option, or the product holds two options with the same
  model and currency, the change is refused and names what would be lost. Keep a
  matching option, or state the floor and the minimum spend on each option. An
  option the source stores with
  `parameters`, such as a digital out-of-home flat rate, refuses every price
  change, because the sales agent's price write takes no `parameters` and the
  change could not send them back.
* If you change prices without a `deliveryType`, the tool reads the product's
  stored delivery type and uses it.
* A change with `id` and no other field is refused as nothing to change.
* A change cannot empty `channels`.
* The fields `includedAgeSignal`, `audienceEvidence` and the
  [show and episode fields](https://docs.apostra.com/v3/seller-product-creation.md#sell-shows-and-episodes)
  follow one rule: omit to keep, a value to replace, `null` to clear.
* `fixedTargeting` changes part by part; see
  [Change fixed targeting](https://docs.apostra.com/v3/seller-product-creation.md#change-fixed-targeting).
* `overlaySupport` is kept when you omit it and replaced whole when you send it.
  Send `null` to make the product follow your ad server's targeting again; see
  [Targeting buyers are served](https://docs.apostra.com/v3/seller-product-creation.md#targeting-buyers-are-served-and-the-ad-servers-default).
* `videoPlacementTypes` is kept when you omit it, replaced whole when you send a
  list, and cleared by `[]`; see
  [Video placement types](https://docs.apostra.com/v3/seller-product-creation.md#video-placement-types).

## Price a product in any AdCP pricing model

A price option names any pricing model AdCP defines: `cpm`, `vcpm`, `cpc`,
`cpcv`, `cpv`, `cpp`, `cpa`, `revenue_share`, `flat_rate` or `time`. The option
keeps AdCP's names for the fields it takes: `pricing_model`, `currency`,
`fixed_price` and `min_spend_per_package`. The tool checks each option against
AdCP's own option for its model and names the field when one is refused.

| `pricing_model` | `fixed_price` is |
| - | - |
| `cpm` | The price per 1,000 impressions. |
| `vcpm` | The price per 1,000 viewable impressions. |
| `cpc` | The price per click. |
| `cpcv` | The price per completed view. |
| `flat_rate` | The flat cost, whatever the delivery. |

An option with no `fixed_price` is an auction. `min_spend_per_package` is the
option's least spend per package, in the option's currency. The other models
need more than these fields: `cpv`, `cpp` and `time` need AdCP `parameters` (a
view threshold, a demographic, a time unit), a digital out-of-home flat rate
sets its share of voice in `parameters`, and `cpa` and `revenue_share` carry
conversion-event or commission fields. A price option does not take any of these
yet.

```json theme={null}
{
  "sourceId": "SOURCE_ID",
  "id": "PRODUCT_ID",
  "deliveryType": "non_guaranteed",
  "pricingOptions": [
    { "pricing_model": "vcpm", "currency": "USD", "fixed_price": 9 },
    { "pricing_model": "cpc", "currency": "USD", "fixed_price": 0.8, "min_spend_per_package": 500 }
  ]
}
```

An auction states its floor in `floor_price` instead of a `fixed_price`:

```json theme={null}
{
  "sourceId": "SOURCE_ID",
  "id": "PRODUCT_ID",
  "deliveryType": "non_guaranteed",
  "pricingOptions": [
    { "pricing_model": "vcpm", "currency": "USD", "floor_price": 3.5 },
    { "pricing_model": "cpm", "currency": "USD", "floor_price": 2 }
  ]
}
```

### A source sells fewer models than AdCP defines

The tool refuses a price the source cannot sell, rather than save it and lose
it. The refusal is `VALIDATION_ERROR` and names the option (`pricingOptions[1]`),
its model, the source and the reason. Nothing is written. It applies to a create,
a change and a dry run alike. Two things limit a source:

* **Its ad server books only some models.** Read `pricingModels` from `get` of the
  source with `include: ["capabilities"]`
  ([Browse an ad-server source](https://docs.apostra.com/v3/seller-browse-ad-server-source.md#capabilities)).
  A source that reports none sells `cpm` only. `cpm` is always accepted, so a call
  that prices only in `cpm` makes no extra read. For any other model the tool
  reads the source's capabilities first, and a read that fails fails the call.
* **The managed sales agent stores and publishes only part of AdCP's option.**
  Today it sells a fixed `cpm`, `vcpm`, `cpc`, `cpcv` or `flat_rate` price, and a
  `cpm` auction. It does not carry `cpa`, `revenue_share` or `time`, nor `cpv` or
  `cpp` (their required `parameters` cannot be stored), nor any `parameters` on a
  flat rate. It publishes a `cpcv` or `flat_rate` price only as a fixed price, and
  a `vcpm` or `cpc` auction only with a floor or other price guidance. Give such
  an auction a `floor_price`, or keep the product's stored auction of that model
  and currency in a change, whose floor and guidance carry over. Otherwise give a
  `fixed_price`. Each limit is lifted when the sales agent ships the missing
  piece.

Reads return a stored option in AdCP's form for its model: `fixed_price` on a
fixed option, `floor_price` and `price_guidance` on an auction, the minimum spend
as a number, and `parameters` when the source stored any, for example on a
digital out-of-home flat rate.

## Take a product off the market, or delete it

`status: "archived"` stops buyers from seeing a product and is reversible. Save
`status: "active"` to bring the same product back.

`delete: true` removes the product from the source for good. The tool enforces
three conditions before it deletes:

1. The product is `draft` or `archived`. An `active` product is refused with
   `refused: "product_not_off_market"` and `nextAction: "archive_first"`.
2. You pass `confirmName`, the product's exact stored name. Read the product
   with `get`, show the operator its name, and send that name back. A wrong
   name is refused with `name_confirmation_mismatch`, and the stored name is not
   echoed to you.
3. The call carries no other field. A delete cannot also edit, and it cannot be
   dry-run.

Deleting a product that no longer exists reports `action: "unchanged"` with
`code: "NOT_FOUND"` instead of failing. Deleting does not touch the ad-server
inventory the product packaged. To sell that inventory again, create a new
product, which gets a new id.

The Components widget follows the same rule: it offers Delete only on a draft or
archived product, and asks you to archive an active product first.

## Read the result

A successful save returns `saved: true` with these fields:

| Field | Meaning |
| - | - |
| `created` | `true` for a create, `false` for a change. |
| `id`, `sourceId` | The product and its source. |
| `status` | The status the source holds after the write, read from the source and not echoed from your request. |
| `pricingStatus` | Whether the source could resolve a price: `priced`, `unresolved` or `ignored`. Ad-server and uploaded pricing are guidance, so an `unresolved` product that carries an auction pricing option stays listed to buyers with no floor and no price guidance. A product with no pricing option, or only a fixed price outside your settlement currency, can save and still be hidden. |
| `pricingCurrencyWarning` | Present when a fixed price is in the wrong currency. It names the currency the storefront needs. |
| `warnings` | Advisory findings that did not block the save. |

A status of `active` means the product is eligible. It does not prove buyers
can see it. Buyers read the storefront catalogue, which refreshes after the
save. Check buyer visibility with `get` once it has.

## Find and inspect products

List a source's products with `search`:

```json theme={null}
{
  "kind": "wholesale_product",
  "sourceId": "SOURCE_ID",
  "filter": { "productStatus": "draft" }
}
```

`filter.productStatus` is `draft`, `active` or `archived`. Each result has an
`origin`: `ad_server` for a product you author, `modular_source` for one a
modular source offers, and `agent_source` for one a third-party sales agent
publishes. You change the last two at their source.

A search without a `sourceId` lists the products of your ad-server and modular
sources and names the third-party sales agent sources it did not read. Pass one
of those as `sourceId` to list its products.

Read one product with `get`. It needs the `sourceId`:

```json theme={null}
{ "kind": "wholesale_product", "id": "PRODUCT_ID", "sourceId": "SOURCE_ID" }
```

The read returns what was saved, including `inventory`, `channels`,
`formatOptions`, `pricingOptions`, `deliveryType` and
[`prebidIntegrationActive`](https://docs.apostra.com/v3/seller-prebid-toggle). It also returns:

* `videoPlacementTypes` and `overlaySupportSource`, described under
  [Video placement types](https://docs.apostra.com/v3/seller-product-creation.md#video-placement-types) and
  [Targeting buyers are served](https://docs.apostra.com/v3/seller-product-creation.md#targeting-buyers-are-served-and-the-ad-servers-default);
* `buyerVisibility`, which is `visible`, or `hidden` with the check that failed,
  such as a paused storefront, a catalogue that has not warmed, unresolved
  pricing, no price in a storefront currency, or
  [a restriction to named buyer accounts](https://docs.apostra.com/v3/seller-restricted-products.md);
* `inferredChannels`, a guess made from the formats, shown only when you have
  declared none. It is never stored; and
* `composerCompleteness.missing`, the facts the proposal composer still needs.
  The composer can pitch an active product only when it has a channel, a
  canonical format and a priced option with a currency and delivery type.

### Read a third-party sales agent's products

A third-party sales agent holds its own products. Apostra keeps the last copy
the agent published and serves it to buyers, so `search` and `get` with that
source's `sourceId` list it, including each product's `formatOptions` and
prices. The copy is read-only: change a product in the agent, and
`save_wholesale_product` on this source is refused.

The result says when the copy was last fetched. If the latest fetch failed, the
products from the last good fetch are still listed and the result says the copy
may be out of date. If nothing has been fetched yet, or the agent publishes no
catalogue Apostra can read, the search names the source as one it could not
read. That is not the same as the agent having no products. A sales agent need
not report a product status, so `status` can be `unknown`. The count line says
how many products have no status and does not count them as inactive;
`buyerVisibility` says whether buyers can find each product. Each product comes
back with `origin: "agent_source"`.

## Seller-fixed and buyer-chosen targeting

A wholesale product is the inventory it sells, the targeting you fix on it, and
the targeting a buyer may add. On a Google Ad Manager product:

| Targeting | Who sets it | Field |
| - | - | - |
| Ad units and placements the product sells | You | `ad_unit` and `placement` selectors in `inventory.execution` |
| Countries every line item runs in | You | `fixedTargeting.geo.geo_countries` |
| Key-values every line item must include, such as a position | You | `fixedTargeting.key_values.include` |
| Key-values every line item must exclude (is-not), such as a child-directed or restricted-content key | You | `fixedTargeting.key_values.exclude` |
| Which dimensions a buyer may target | You | `overlaySupport` |
| Key-values and geography a buyer targets, within what you allow | The buyer, per buy | The buyer's package targeting |

### Fix targeting on a product

`fixedTargeting` holds the targeting every line item booked from the product
carries:

```json theme={null}
{
  "sourceId": "SOURCE_ID",
  "id": "PRODUCT_ID",
  "fixedTargeting": {
    "geo": { "geo_countries": ["US"] },
    "key_values": {
      "include": [{ "key_id": "3001", "value_ids": ["4001"] }],
      "exclude": [
        { "key_id": "3010", "value_ids": ["4010"] },
        { "key_id": "3011", "value_ids": ["4011"] }
      ]
    }
  },
  "overlaySupport": { "device_type": true }
}
```

* `geo.geo_countries` takes ISO 3166-1 alpha-2 codes, AdCP's
  `geo_countries`. Every line item runs in these countries. A buyer who names
  no country gets them, and a buyer who asks for a country outside them is
  refused, with the allowed countries named. Only countries can be fixed today.
* `key_values` names your Google Ad Manager custom-targeting keys and values by
  their ids, as your inventory sync holds them. An `include` entry targets the
  key with any of its values; an `exclude` entry targets the key with none of
  them. Every entry applies to every line item, together. Give each key one
  entry across `include` and `exclude`, listing all its values there.
* A key or value your inventory sync does not hold is refused, naming it.
* A buyer's own targeting is added on top of the fixed targeting. It can narrow
  a buy, never remove or widen what you fixed.
* Fixed targeting is for Google Ad Manager sources; other sources refuse it.

### Change fixed targeting

A change to `fixedTargeting` works part by part. The parts are `geo`,
`key_values.include` and `key_values.exclude`.

* Omit a part to keep it. Send a part to replace it. Send it as `null` to remove
  it; `key_values: null` removes both lists.
* A change to one part never removes another. Changing the countries or the
  includes keeps the exclusions you have stored.
* `fixedTargeting: null` removes all of it. Leaving `fixedTargeting` out of a
  change keeps all of it.
* Empty values are refused: `{}` for `fixedTargeting` or `key_values`, and `[]`
  for `include` or `exclude`. Only `null` removes.
* A key can be in `include` or `exclude`, not both. A change that adds a key to
  one list while your stored other list holds it is refused, naming the key.
* Line items already booked pick up the product's current fixed key-values the
  next time their targeting is changed.

`overlaySupport` is the product's AdCP `overlay_support`: the targeting
dimensions a buyer may set on a package. It is a permission, not a value, and
never adds targeting to a buy. To allow no buyer geography, leave the geo
dimensions out of it. See [Targeting buyers can book](https://docs.apostra.com/v3/seller-product-creation.md#targeting-buyers-can-book).

Before you make the product `active`, dry-run it and read `lineItemTargeting`,
which shows the countries, key-values and exclusions exactly as Google Ad
Manager will receive them.

### What the tool does with GAM selectors

* A GAM selector's `selector_type` is `ad_unit` or `placement`. Any other type is
  refused with `unsupported_selector_type`. A key-value is fixed targeting, not
  a selector type.
* A selector's `options` on GAM takes one key: `include_descendants` on an
  `ad_unit` selector. Any other option key is refused with
  `unknown_selector_option`, naming the key. When you do not state it and the ad
  server says the ad unit has children, a save sets it to `true` for you, and a
  value you send is kept as sent. See
  [Ad units with children](https://docs.apostra.com/v3/seller-browse-ad-server-source.md#ad-units-with-children).

### Targeting buyers can book

A product's declared targeting, its AdCP `overlay_support`, is what buyers can
set on a package for that product: dimensions such as countries, regions,
Nielsen DMA metros or a frequency cap, the metro and postal systems you list,
and any per-package limits. Set it with `overlaySupport` on
`save_wholesale_product` or in the product editor; the field rules are in
[Create products from ad-server inventory](https://docs.apostra.com/v2/storefront/inventory-sources/create-products.md).
Buyers read it on the product, so a declaration is a promise: your fixed prices
and floors still apply to every selection you allow. Buyers see
`signal_targeting_groups` only on a product that offers them signals to add
(`signal_targeting_allowed: true`), as AdCP requires. Property signals do not
count, because Apostra manages them. A product from your Apostra-managed sales
agent offers buyers the signals your agent serves in `get_signals`, even when
the product lists none of its own or only property signals, so it keeps the
groups while buyers can see at least one of your signals there and is shown
without them when they can see none. To let buyers add signals to a product,
keep `signal_targeting_groups` in its `overlaySupport`.

Every media buy is checked against the declaration when the buyer saves a
draft, books, or changes targeting, including targeting the package inherits
from its campaign. This happens before the buy reaches your approval queue or
your sales agent. A package that targets a dimension the product doesn't
declare, a metro or postal system it doesn't list, or more values than a
per-package limit allows is refused, and nothing reaches you. The buyer sees
the refusal straight away, naming the package, the product and the targeting.
Buys already running are not re-checked; a later targeting change to one is.

A product on your managed sales agent that you haven't narrowed publishes the
targeting your ad server can apply, and buyers are held to it as they are to a
declaration you made yourself. It follows your ad server as its support changes.
A product on any other source that declares no targeting of its own isn't
checked this way. Your seller-wide targeting applies to it, and your sales agent
still refuses anything your ad server can't apply.

What buyers see, and the errors they get, is in
[Targeting each product offers](https://docs.apostra.com/v3/campaign-targeting.md#targeting-each-product-offers).

### Targeting buyers are served, and the ad server's default

A product that declares no `overlaySupport` follows your ad server: buyers are
offered what the ad server can apply, and that changes as the ad server's
support does. A read says which case a product is in with `overlaySupportSource`:

| `overlaySupportSource` | Meaning |
| - | - |
| `explicit` | You declared the targeting. `overlaySupport` holds it. |
| `adapter_default` | You declared none, so the product follows the ad server. `overlaySupport` is `null`. |
| `null` | The source does not say. |

`overlaySupport` always returns what you declared, so a product that follows its
ad server reads `null`. Sending a read back unchanged never turns the default
into a declaration of your own.

To read what buyers are served, `get` the product with
`include: ["effectiveOverlaySupport"]`:

```json theme={null}
{
  "kind": "wholesale_product",
  "sourceId": "SOURCE_ID",
  "id": "PRODUCT_ID",
  "include": ["effectiveOverlaySupport"]
}
```

`effectiveOverlaySupport` is your declaration when you made one, and otherwise
the ad server's default, in AdCP's `overlay_support` shape. It is `null` when
the source reports none, and for a product read from a modular source or a
third-party sales agent. It is on `get` only: an ad server default can be large
(a FreeWheel one is about 42 KB), so `search` and a plain `get` leave it out.

A declaration replaces the default whole, so declaring one dimension offers
buyers that one dimension and nothing else. Read `effectiveOverlaySupport`, edit
that declaration, and send it. To go back to the ad server's default, send
`overlaySupport: null`. It removes your own declaration. A new product follows
its ad server until you declare targeting, so `null` on a create changes
nothing.

## Video placement types

A product with video formats can declare the video placement types it delivers
with `videoPlacementTypes`. The values are AdCP's four, which use the IAB Tech
Lab OpenRTB 2.6 `plcmt` definitions: `instream`, `accompanying_content`,
`interstitial` and `standalone`. It is seller-declared discovery metadata:
Apostra does not check it against the product's formats.

* Omit it to keep the stored list. Send a list to replace it whole. Send `[]` to
  clear it. Each value may appear once, and a value AdCP does not define is
  refused.
* `get` and `search` return `videoPlacementTypes`, or `null` when the product
  declares none. `[]` is the instruction to clear, not a stored value, so a read
  never returns it.

```json theme={null}
{
  "sourceId": "SOURCE_ID",
  "id": "PRODUCT_ID",
  "videoPlacementTypes": ["instream", "interstitial"]
}
```

## Sell shows and episodes

A podcast or video network sells its inventory by show and by episode. AdCP
calls a show a collection and an episode an installment. Declare them on a
product with four fields, each holding AdCP's own object under AdCP's field
names:

| Field | AdCP field | What it says |
| - | - | - |
| `collections` | `collections` | The shows the product sells. Each entry is a `publisher_domain` and the `collection_ids` that publisher's `adagents.json` declares. `[]` says the product sells shows it does not disclose. |
| `installments` | `installments` | The episodes the product sells. Each is an AdCP installment: an `installment_id`, a `collection_ref` naming its show, and optionally when it airs (`scheduled_at`), its status, its ad breaks (`ad_inventory`) and its booking and material deadlines (`deadlines`). |
| `collectionTargetingAllowed` | `collection_targeting_allowed` | Whether a buyer may buy some of the product's shows rather than all of them. |
| `holdPolicy` | `hold_policy` | Whether a buyer can hold the product's inventory before booking it. |

```json theme={null}
{
  "sourceId": "SOURCE_ID",
  "id": "PRODUCT_ID",
  "collections": [
    {
      "publisher_domain": "northwind-audio.example",
      "collection_ids": ["weeknight-kitchen", "the-baking-hour"]
    }
  ],
  "installments": [
    {
      "installment_id": "weeknight-kitchen-47",
      "collection_ref": {
        "publisher_domain": "northwind-audio.example",
        "collection_id": "weeknight-kitchen"
      },
      "scheduled_at": "2026-12-01T10:00:00Z",
      "ad_inventory": { "expected_breaks": 2, "total_ad_seconds": 150 }
    }
  ],
  "collectionTargetingAllowed": false,
  "holdPolicy": { "available": false }
}
```

* Each field is checked against AdCP when you save, and a refusal names the
  field. When the product lists its shows, each episode's show must be one of
  them, and an episode id can appear only once within its show.
* Omit a field to keep it, send a value to replace it whole, or send `null` to
  clear it. `get` and `search` return each one as stored, and `null` when the
  product has none.
* Buyers see the shows, the episodes and `collection_targeting_allowed` on the
  product. A buy that names some of the shows is checked against them; see
  [Buying some of a product's shows](https://docs.apostra.com/v3/campaign-targeting.md#buying-some-of-a-products-shows).
* Set `collectionTargetingAllowed: true` only when your ad server can book some
  of the product's shows on their own. No ad server that Apostra's sales agent
  supports can do that today, so the source refuses `true` and names your ad
  server. Leave it `false` and sell each show you want sold on its own as its
  own product.
* Buyers choose among a product's shows, not among its episodes. To sell
  particular episodes, make a product for each episode, or for each run of
  episodes, and list them in its `installments`.
* No ad-server source can hold inventory before a buy is booked yet, so the one
  hold policy you can save is `{ "available": false }`. A policy with
  `available: true` is refused, and the refusal names the source. Buyers do not
  see the hold policy yet: AdCP marks it experimental, and storefronts serve
  products to buyers in an earlier AdCP version.

## Limits

* The tool needs a Seller Account.
* V3 has no tool for bulk product creation, for the wholesale avails
  percentile-CPM feed, or for searching ad-server selectors. Create products one
  at a time with `save_wholesale_product`.

## Where bulk pricing uploads appear

V3 does not upload a bulk wholesale-pricing feed. When you commit one in the
seller workspace, open **Changes** to verify it. A successful upload records
the source, actor, import, row counts, selector-match summary and effective
window. Previews and rejected uploads do not create a Changes record.

A commit replaces the source's prior complete feed, so a selector left out of the new file stops being priced. A
commit is refused while any row of the file is rejected, and a successful commit refreshes the source's products.

## Related

* [Create products from ad-server inventory](https://docs.apostra.com/v2/storefront/inventory-sources/create-products.md)
* [Declare the Apostra Prebid module on a product](https://docs.apostra.com/v3/seller-prebid-toggle.md)
* [Restrict a product to named buyer accounts](https://docs.apostra.com/v3/seller-restricted-products.md)
* [Seller workflows](https://docs.apostra.com/v2/setup/v3/seller-workflows.md#add-and-diagnose-inventory)


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