Overview
Buyer instructions let you tailor how your storefront responds to a specific buyer. Each row scopes a discount, freeform notes, and an optional country filter to an exact buyer identity. When a buyer’s request matches a row, the Merchandising Agent applies that row’s discount and notes while composing products for the response. For a plain entity discount — “Coke gets 20%”, “everything GroupM buys gets 8%”, “the Nike family gets 12%” — reach for a house discount instead: it’s the structured rate-card rail, keyed to a brand or operator and resolved up the hierarchy. Buyer instructions are for what that rail can’t express:- the intersection — a discount that requires a specific operator and a specific brand together (a house discount resolves the two axes independently)
- country-specific terms (
countries) - freeform notes the Merchandising Agent reads during composition
discountPercent for the intersection
case; when both rails match a buy, the larger discount applies.
A buyer instruction only resolves once a buy carries an AdCP account
reference — it identifies the buyer. Anonymous (no-account) discovery stays
public and can only inherit a house discount.
(operatorDomain, brandDomain) tuple, which is unique per
storefront. The two fields combine into one of four shapes:
| Scope shape | operatorDomain | brandDomain | Applies to |
|---|---|---|---|
| Storefront default | null | null | Any identified buyer (your default) |
| Brand | null | set | Any operator buying for this brand |
| Operator | set | null | This operator, any brand |
| Operator + brand | set | set | This operator buying for this brand |
The resolver picks the maximum
discountPercent across all matching rows.
Adding a brand-specific row only wins by being a better deal than the rows it
overlaps with. These are exact matches — buyer instructions do not walk the
brand hierarchy. To reach a whole corporate family, use a
house discount.operatorDomain or brandDomain,
delete the
row and
create a
new one.
Fields
| Field | Type | Description |
|---|---|---|
operatorDomain | string | null | Operator (e.g. agency or DSP) the row applies to, or null to match any operator. 1–253 chars |
brandDomain | string | null | Advertiser brand the row applies to, or null to match any brand. 1–253 chars |
discountPercent | number | null | Discount percent off the storefront base price for matching buys. 0–100. null = no discount contribution |
notes | string | null | Freeform notes the Merchandising Agent applies to compositions for matching buyers. Max 2000 chars. null = no notes contribution |
countries | string[] | null | ISO 3166-1 alpha-2 codes (uppercase). Row applies only when the buy targets one of these countries. null = applies regardless of country |
Tasks
List buyer instructions
Read every row on the storefront.
Create buyer instructions
Add a new scoped row.
Update buyer instructions
Change discount, notes, or countries on a row.
Delete buyer instructions
Remove a row by id.
Related
House discounts
The corporate-house rail of buyer discounts.
Storefront overview
How buyer instructions fit alongside operating instructions.
Intelligence runs
See which rows matched and the effective discount applied per run.