> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semicola.com/llms.txt
> Use this file to discover all available pages before exploring further.

# House discounts and buyer instructions

> Give a buyer brand or operator a negotiated discount, notes or country limits that your storefront agent applies when it composes proposals.

Two playbook sections tailor what a specific buyer is offered:

| Section                | Keyed to                                    | Carries                                        |
| ---------------------- | ------------------------------------------- | ---------------------------------------------- |
| **House discounts**    | One domain, as a `brand` or an `operator`   | A discount percent and notes.                  |
| **Buyer instructions** | An operator domain, a brand domain, or both | A discount, countries and notes for the agent. |

A **brand** is the advertiser whose products are advertised (`glazeandco.example`). An **operator** is
whoever does the buying for it: an agency, a trading desk or the brand's own team. Both sections live on
the [Playbook](/sell/playbook) page.

## House discounts

"Glaze & Co. gets 10%" is a `brand` discount on `glazeandco.example`; "everything this agency buys
gets 8%" is an `operator` discount on the agency's domain.

| Field             | Notes                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------- |
| `houseDomain`     | The domain it's keyed to. Stored lower-case, without `www.`.                                   |
| `scope`           | `brand` matches the advertiser's brand domain; `operator` matches the buyer's operator domain. |
| `discountPercent` | Percent off your quote, 0–100 (applied up to 50; see below).                                   |
| `notes`           | Your notes, for example where the rate came from.                                              |

Each axis resolves up the buyer's own brand hierarchy, read from its published `brand.json` (the
`house` it names), so one row covers a corporate family: a `brand` discount on `nike.com` reaches a
Converse buy when `converse.com`'s `brand.json` names `nike.com` as its house. A subdomain also
reaches its parent domain (`shop.glazeandco.example` → `glazeandco.example`).

* **Nearest wins within an axis.** A discount on the exact domain beats one on its house; a parent
  never overrides a more specific descendant.
* **Larger wins across axes.** When a brand discount and an operator discount both match, the buyer
  gets the larger one; a tie goes to the brand axis.

When an agency publishes no resolvable `brand.json`, key an `operator` discount on the exact domain.

## Buyer instructions

A buyer instruction names an `operatorDomain`, a `brandDomain`, or both, and applies only when every
domain it names matches the buyer. Use it for what a house discount can't say:

* a discount that needs a specific operator **and** brand together;
* **countries**: limit this buyer to the listed ISO country codes;
* **notes** the storefront agent reads while composing (up to 4,000 characters).

| Field             | Notes                                                         |
| ----------------- | ------------------------------------------------------------- |
| `operatorDomain`  | The operator it applies to (optional).                        |
| `brandDomain`     | The brand it applies to (optional). At least one is required. |
| `discountPercent` | Optional, 0–50.                                               |
| `countries`       | Optional two-letter country codes.                            |
| `notes`           | Optional.                                                     |

Instructions match exact domains only; they don't walk the brand hierarchy. When several match, the
**largest** `discountPercent` among them applies. The agent reads the notes of every matching
instruction, most specific (naming more domains) first, and takes the countries from the most
specific one.

## Which discount applies

1. The house discount chosen as above, and the largest matching buyer-instruction discount.
2. When both rails match, the buyer gets the **larger** of the two.
3. The discount is capped at 50%, and a price never goes below your hard floor: a discount can bring a
   quote down to the floor, never under it.

Buyer terms need the buyer's brand or operator domain. A request that carries neither gets no house
discount and no buyer instruction.

## Save and preview

In the app, edit **House discounts** and **Buyer instructions** on the Playbook page, then use
**Resolve preview**: enter a **Brand domain** and **Operator domain** to see the **Discount** that
would apply, where it comes **From**, the **Countries** and the **Notes**.

Over MCP, `save_playbook` takes `discounts` and `buyerInstructions`. Each list replaces the whole
section when you send it, so send every row you want to keep; an empty list clears the section.

```json save_playbook theme={null}
{
  "discounts": [
    { "houseDomain": "glazeandco.example", "scope": "brand", "discountPercent": 10, "notes": "2027 upfront" }
  ],
  "buyerInstructions": [
    {
      "operatorDomain": "agency.example",
      "brandDomain": "glazeandco.example",
      "discountPercent": 15,
      "countries": ["US", "CA"],
      "notes": "Lead with CTV; they renew in Q1."
    }
  ]
}
```

## Not available yet

* A storefront-wide default instruction with neither domain set.
* REST endpoints for house discounts and buyer instructions.

## Related

* [Playbook](/sell/playbook)
* [Operating instructions and policy versions](/sell/operating-instructions)