Skip to main content
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. 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: 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.
  • 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.
  • 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:
    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 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.
  • pricingOptions are replaced whole. Send every price you want to keep. 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 follow one rule: omit to keep, a value to replace, null to clear.
  • fixedTargeting changes part by part; see 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.
  • videoPlacementTypes is kept when you omit it, replaced whole when you send a list, and cleared by []; see 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. 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.
An auction states its floor in floor_price instead of a fixed_price:

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). 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: 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:
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:
The read returns what was saved, including inventory, channels, formatOptions, pricingOptions, deliveryType and prebidIntegrationActive. It also returns:
  • videoPlacementTypes and overlaySupportSource, described under Video placement types and Targeting buyers are served;
  • 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;
  • 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:

Fix targeting on a product

fixedTargeting holds the targeting every line item booked from the product carries:
  • 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. 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.

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

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

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