> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/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>