Create buyer instructions

POST /api/v2/storefront/buyer-instructions Creates a new buyer-instructions row. The (operatorDomain, brandDomain) tuple is unique per storefront — a duplicate scope fails with 409. To change an existing row, update it instead.

Request

curl

curl -X POST https://api.interchange.io/api/v2/storefront/buyer-instructions \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operatorDomain": "acme-media.com",
    "brandDomain": "northwind.example",
    "discountPercent": 15,
    "notes": "Brand requires Acme Media viewability ≥ 70%.",
    "countries": ["US", "CA"]
  }'

Parameters

All five fields are required. Send null for any you want to leave unscoped.

Field	Type	Required	Notes
`operatorDomain`	string \| null	Yes	Operator the row applies to, or `null` for any operator. 1–253 chars
`brandDomain`	string \| null	Yes	Brand the row applies to, or `null` for any brand. 1–253 chars
`discountPercent`	number \| null	Yes	Discount off base price, `0`–`100`. `null` for no discount
`notes`	string \| null	Yes	Composition notes, max 2000 chars. `null` for no notes
`countries`	string[] \| null	Yes	ISO 3166-1 alpha-2 codes (uppercase), at least one when set. `null` for all countries

Response

{
  "id": "18",
  "storefrontId": "1234",
  "operatorDomain": "acme-media.com",
  "brandDomain": "northwind.example",
  "discountPercent": 15,
  "notes": "Brand requires Acme Media viewability ≥ 70%.",
  "countries": ["US", "CA"],
  "createdAt": "2026-06-06T15:00:00.000Z",
  "updatedAt": "2026-06-06T15:00:00.000Z",
  "createdBy": "operator@touchline.example"
}

Returns 201 with the created row. The resolver picks the maximum discountPercent across all rows that match a given buyer.

Errors

400 VALIDATION_ERROR — missing required field, discountPercent out of 0–100, or a malformed country code.
409 CONFLICT — a row already exists for this (operatorDomain, brandDomain) scope. Update that row instead.
401 UNAUTHORIZED — missing or invalid bearer token.

See Errors for the full error contract.

Buyer instruction tasks

All buyer-instructions operations.

Update buyer instructions

Change discount, notes, or countries.

Buyer instruction tasks Delete buyer instructions

⌘I

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

Request

Parameters

Response

Errors

Buyer instruction tasks

Update buyer instructions

​Request

​Parameters

​Response

​Errors

​Related

Buyer instruction tasks

Update buyer instructions

Request

Parameters

Response

Errors

Related