> ## 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.

# Update buyer instructions

> Change discount, notes, or countries on a buyer-instructions row

`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](/v2/storefront/buyer-instructions/tasks/delete-buyer-instructions) and
recreate the row to change them.

## Request

```bash curl theme={null}
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

```json theme={null}
{
  "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](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Buyer instruction tasks" href="/v2/storefront/buyer-instructions/tasks" icon="list-check">
    All buyer-instructions operations.
  </Card>

  <Card title="Delete buyer instructions" href="/v2/storefront/buyer-instructions/tasks/delete-buyer-instructions" icon="trash">
    Remove a row to change its scope.
  </Card>
</CardGroup>