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 itssourceId, 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 noid. It needs name, channels and inventory with an
inventory.execution block. When you send pricingOptions you also send
deliveryType.
-
channelsare AdCP media channels. The tool refusesaudioandvideo, 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. -
inventoryhas two parts.inventory.executionis how the ad server runs the product, and buyers never see it.inventory.publisher_propertiesis the publisher scope buyers see, as AdCP publisher selectors (publisher_domain,selection_typeand, forby_idorby_tag,property_idsorproperty_tags). Both are closed: the tool refuses a field it does not list. -
inventory.executionneeds anadapter(the source’s ad-server adapter) and carries theselectorsto sell and anyformat_bindings. A selector is aselector_type, anexternal_idand optionally anameandoptions. A format binding is aformat_option_idand optionally anadapter_config. The tool refuses a create withoutinventory.executionand itsadapterbefore 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
optionsand a format binding’sadapter_configdepend on the ad server, so each is a list of{ "key", "value" }entries, one per setting.keyis 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.valueis a string, a number, a boolean, a list of strings,nullor 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. -
getandsearchreturninventoryin the shape a save takes:executionunder the names above, eachoptionsandadapter_configas entries, andpublisher_propertiesas AdCP selectors. To change one setting, read the product, edit itsinventory, and send the wholeinventoryback. Setting names come back exactly as stored. -
A change may leave
executionout (or send it asnull) and keeps the stored one. Anexecutionit does send needs anadapterand replaces the stored block whole, so anyselectorsorformat_bindingsit leaves out are no longer on the product: send the complete block you want.publisher_propertiesis replaced whole the same way, and[]clears it. -
The older open
inventory, whereoptionsandadapter_configare objects and any other key is passed through, still works for now. Send entries instead: the open form will be removed. -
statusisdraft,activeorarchived. Adraftis hidden from buyers. The result states the status the source gave the product. Savestatus: "active"when the product is ready. -
fixed_pricecan be0. A$0fixed price is a complete price that buyers can see and book, for donated, house or added-value inventory. It is not the same as leavingfixed_priceout: an option with nofixed_priceis an auction and keeps listing with no floor and no price guidance. Afixed_pricecannot be negative. Thefixed_pricestill has to be in your settlement currency to list. A$0price makes the product visible and bookable at that price. A buyer books it with a$0budget and states the delivery owed as an impressions goal, which reaches you as the package’simpressions. -
min_spend_per_packageis 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_priceis 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 afixed_price, because AdCP makes the two exclusive. A floor of0on acpmauction means no floor is declared. V3 sends the floor to the managed sales agent unchanged and never writes it intoprice_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, carriesdetails.outcomeofsaved_floor_unconfirmed, and setsrecoverytoterminal, which outranks itsSERVICE_UNAVAILABLEcode. 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 aserrors, each with acode, amessageand afieldwhen the source named one. Advisory findings do not block the save and come back aswarnings.
Check a create without saving it
AdddryRun: 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 productid and only the fields you want to change. Every field you
omit keeps its stored value.
pricingOptionsare 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_modelandcurrency. Afloor_priceormin_spend_per_packageyou state on the option replaces the stored one. The floor stays only while that option is still an auction: afixed_pricereplaces 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 withparameters, such as a digital out-of-home flat rate, refuses every price change, because the sales agent’s price write takes noparametersand 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
idand no other field is refused as nothing to change. - A change cannot empty
channels. - The fields
includedAgeSignal,audienceEvidenceand the show and episode fields follow one rule: omit to keep, a value to replace,nullto clear. fixedTargetingchanges part by part; see Change fixed targeting.overlaySupportis kept when you omit it and replaced whole when you send it. Sendnullto make the product follow your ad server’s targeting again; see Targeting buyers are served.videoPlacementTypesis 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.
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 isVALIDATION_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
pricingModelsfromgetof the source withinclude: ["capabilities"](Browse an ad-server source). A source that reports none sellscpmonly.cpmis always accepted, so a call that prices only incpmmakes 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,cpcvorflat_rateprice, and acpmauction. It does not carrycpa,revenue_shareortime, norcpvorcpp(their requiredparameterscannot be stored), nor anyparameterson a flat rate. It publishes acpcvorflat_rateprice only as a fixed price, and avcpmorcpcauction only with a floor or other price guidance. Give such an auction afloor_price, or keep the product’s stored auction of that model and currency in a change, whose floor and guidance carry over. Otherwise give afixed_price. Each limit is lifted when the sales agent ships the missing piece.
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:
- The product is
draftorarchived. Anactiveproduct is refused withrefused: "product_not_off_market"andnextAction: "archive_first". - You pass
confirmName, the product’s exact stored name. Read the product withget, show the operator its name, and send that name back. A wrong name is refused withname_confirmation_mismatch, and the stored name is not echoed to you. - The call carries no other field. A delete cannot also edit, and it cannot be dry-run.
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 returnssaved: 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 withsearch:
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:
inventory, channels,
formatOptions, pricingOptions, deliveryType and
prebidIntegrationActive. It also returns:
videoPlacementTypesandoverlaySupportSource, described under Video placement types and Targeting buyers are served;buyerVisibility, which isvisible, orhiddenwith 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; andcomposerCompleteness.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, sosearch 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_countriestakes ISO 3166-1 alpha-2 codes, AdCP’sgeo_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_valuesnames your Google Ad Manager custom-targeting keys and values by their ids, as your inventory sync holds them. Anincludeentry targets the key with any of its values; anexcludeentry targets the key with none of them. Every entry applies to every line item, together. Give each key one entry acrossincludeandexclude, 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 tofixedTargeting 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
nullto remove it;key_values: nullremoves both lists. - A change to one part never removes another. Changing the countries or the includes keeps the exclusions you have stored.
fixedTargeting: nullremoves all of it. LeavingfixedTargetingout of a change keeps all of it.- Empty values are refused:
{}forfixedTargetingorkey_values, and[]forincludeorexclude. Onlynullremoves. - A key can be in
includeorexclude, 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_typeisad_unitorplacement. Any other type is refused withunsupported_selector_type. A key-value is fixed targeting, not a selector type. - A selector’s
optionson GAM takes one key:include_descendantson anad_unitselector. Any other option key is refused withunknown_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 totruefor 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 AdCPoverlay_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 nooverlaySupport 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 withvideoPlacementTypes. 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. getandsearchreturnvideoPlacementTypes, ornullwhen 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
nullto clear it.getandsearchreturn each one as stored, andnullwhen the product has none. - Buyers see the shows, the episodes and
collection_targeting_allowedon the product. A buy that names some of the shows is checked against them; see Buying some of a product’s shows. - Set
collectionTargetingAllowed: trueonly 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 refusestrueand names your ad server. Leave itfalseand 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 withavailable: trueis 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.