Skip to main content
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.
FieldTypeRequiredNotes
operatorDomainstring | nullYesOperator the row applies to, or null for any operator. 1–253 chars
brandDomainstring | nullYesBrand the row applies to, or null for any brand. 1–253 chars
discountPercentnumber | nullYesDiscount off base price, 0–100. null for no discount
notesstring | nullYesComposition notes, max 2000 chars. null for no notes
countriesstring[] | nullYesISO 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.