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

# Buyer instructions

> Per-buyer discounts, notes, and country scoping the Merchandising Agent applies when composing products.

## 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](/v2/storefront/house-discounts/overview) 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

A buyer instruction may still carry a `discountPercent` for the intersection
case; when both rails match a buy, the **larger** discount applies.

<Note>
  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](/v2/storefront/house-discounts/overview).
</Note>

A row is scoped by an `(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 |

<Note>
  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](/v2/storefront/house-discounts/overview).
</Note>

The scope columns are immutable. To change `operatorDomain` or `brandDomain`,
[delete](/v2/storefront/buyer-instructions/tasks/delete-buyer-instructions) the
row and
[create](/v2/storefront/buyer-instructions/tasks/create-buyer-instructions) 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

<CardGroup cols={2}>
  <Card title="List buyer instructions" href="/v2/storefront/buyer-instructions/tasks/list-buyer-instructions" icon="list">
    Read every row on the storefront.
  </Card>

  <Card title="Create buyer instructions" href="/v2/storefront/buyer-instructions/tasks/create-buyer-instructions" icon="plus">
    Add a new scoped row.
  </Card>

  <Card title="Update buyer instructions" href="/v2/storefront/buyer-instructions/tasks/update-buyer-instructions" icon="pen">
    Change discount, notes, or countries on a row.
  </Card>

  <Card title="Delete buyer instructions" href="/v2/storefront/buyer-instructions/tasks/delete-buyer-instructions" icon="trash">
    Remove a row by id.
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card title="House discounts" href="/v2/storefront/house-discounts/overview" icon="sitemap">
    The corporate-house rail of buyer discounts.
  </Card>

  <Card title="Storefront overview" href="/v2/storefront/overview" icon="store">
    How buyer instructions fit alongside operating instructions.
  </Card>

  <Card title="Intelligence runs" href="/v2/storefront/intelligence-runs/overview" icon="microscope">
    See which rows matched and the effective discount applied per run.
  </Card>
</CardGroup>


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