Update buyer instructions

PATCH /api/v2/storefront/buyer-instructions/{id} Partially updates a buyer-instructions row. Send only the fields you want to change. The scope columns (operatorDomain, brandDomain) are immutable — delete and recreate the row to change them.

Request

curl

curl -X PATCH https://api.interchange.io/api/v2/storefront/buyer-instructions/17 \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "discountPercent": 20,
    "notes": "Renegotiated for H2; viewability ≥ 70% still required.",
    "countries": ["US", "CA", "GB"]
  }'

Parameters

Field	In	Type	Required	Notes
`id`	path	integer	Yes	Surrogate id of the row to update
`discountPercent`	body	number \| null	No	Discount off base price, `0`–`100`. The resolver picks the MAX across matching rows. `null` clears the discount
`notes`	body	string \| null	No	Composition notes, max 2000 chars. `null` clears the notes
`countries`	body	string[] \| null	No	ISO 3166-1 alpha-2 codes (uppercase), at least one when set. Omit or send `null` for a global row

Response

{
  "id": "17",
  "storefrontId": "1234",
  "operatorDomain": "acme-media.com",
  "brandDomain": "northwind.example",
  "discountPercent": 20,
  "notes": "Renegotiated for H2; viewability ≥ 70% still required.",
  "countries": ["US", "CA", "GB"],
  "createdAt": "2026-05-02T14:21:00.000Z",
  "updatedAt": "2026-06-06T15:00:00.000Z",
  "createdBy": "operator@acme-media.com"
}

Returns 200 with the updated row.

Errors

400 VALIDATION_ERROR — discountPercent out of 0–100, malformed country code, or an attempt to change a scope column.
404 NOT_FOUND — no row with that id on your storefront.
401 UNAUTHORIZED — missing or invalid bearer token.

See Errors for the full error contract.

Buyer instruction tasks

All buyer-instructions operations.

Delete buyer instructions

Remove a row to change its scope.

List buyer instructions House discounts

⌘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

Delete buyer instructions

​Request

​Parameters

​Response

​Errors

​Related

Buyer instruction tasks

Delete buyer instructions

Request

Parameters

Response

Errors

Related