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

# Update Recipient

> Change which merchant notification events a recipient subscribes to

Update a recipient's event subscriptions. The update is **partial**: send only the toggles you are changing, and every key you omit keeps its current value. The response always carries the complete, merged object.

<Note>
  While a store has no explicit recipient, the list contains a fallback entry (`isPrimary: true`, the owner's account email) whose `id` is a sentinel of the form `OWNER_<storeId>`. Sending that id here **materializes** it: the account email becomes a real recipient, your patch is applied on top of the store-level `notify*` toggles, and the response carries a real UUID. The fallback entry then disappears.
</Note>

```
POST /v1/actions/store-notification-recipient/update-recipient
```

**Authentication:** API Key (owner or admin role required)

## Request Body

| Field         | Type   | Required | Description                                                                                                                                            |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `storeId`     | string | Yes      | Store ID (Short ID format `STO_xxx`)                                                                                                                   |
| `recipientId` | string | Yes      | Passed back verbatim from `add-recipient` or the GraphQL query — a UUID for a real recipient, or the `OWNER_<storeId>` sentinel for the fallback entry |
| `preferences` | object | Yes      | The toggles to change. Only the 9 keys in the event catalog are accepted; anything else is rejected with 400.                                          |

## Example Request

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://api.waffo.com/v1/actions/store-notification-recipient/update-recipient \
    -H "Content-Type: application/json" \
    -H "X-Merchant-Id: $WAFFO_MERCHANT_ID" \
    -H "X-Signature: ..." \
    -d '{
      "storeId": "STO_2aUyqjCzEIiEcYMKj7TZtw",
      "recipientId": "11111111-2222-3333-4444-555555555555",
      "preferences": { "notifyNewOrders": false }
    }'
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch(
    "https://api.waffo.com/v1/actions/store-notification-recipient/update-recipient",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Merchant-Id": process.env.WAFFO_MERCHANT_ID,
        "X-Signature": signature,
      },
      body: JSON.stringify({
        storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
        recipientId: "11111111-2222-3333-4444-555555555555",
        preferences: { notifyNewOrders: false },
      }),
    },
  );

  const { data } = await response.json();
  ```
</CodeGroup>

## Success Response (200)

```json theme={"system"}
{
  "data": {
    "recipient": {
      "id": "11111111-2222-3333-4444-555555555555",
      "storeId": "STO_2aUyqjCzEIiEcYMKj7TZtw",
      "email": "ops@acme.com",
      "isPrimary": false,
      "preferences": {
        "notifyNewOrders": false,
        "notifyNewSubscriptions": true,
        "notifySubscriptionCanceled": true,
        "notifySubscriptionRenewed": true,
        "notifySubscriptionEnded": true,
        "notifySubscriptionPastDue": true,
        "notifySubscriptionUncanceled": true,
        "notifySubscriptionPlanChanged": true,
        "notifyChargeback": true
      },
      "createdAt": "2026-08-28T00:00:00.000Z"
    }
  }
}
```

<Note>
  The email address itself is immutable. To move notifications to a different address, add the new recipient and then remove the old one.
</Note>

## Response Fields

| Field         | Type    | Description                                                                     |
| ------------- | ------- | ------------------------------------------------------------------------------- |
| `id`          | string  | Recipient UUID                                                                  |
| `storeId`     | string  | Owning store Short ID                                                           |
| `email`       | string  | Normalized recipient address (unchanged by this endpoint)                       |
| `isPrimary`   | boolean | Always `false` here — materializing the fallback turns it into a real recipient |
| `preferences` | object  | The 9 event toggles after merging your patch                                    |
| `createdAt`   | string  | Creation timestamp (ISO 8601)                                                   |

## Errors

> **Retry policy:** Never retry 4xx — fix the request and resubmit. Retry 5xx with exponential backoff (start 5s, max 3 attempts).

| Status | `errors[0].message`                                               | What it means                                                                                                                  | Recommended handling                                        |
| ------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| 400    | `Missing required field: recipientId`                             | `recipientId` was not provided                                                                                                 | Fix the request body, resubmit                              |
| 400    | `Invalid recipient id format: expected UUID, got "..."`           | `recipientId` is neither a UUID nor this store's sentinel                                                                      | Pass the `id` returned by add-recipient or GraphQL verbatim |
| 400    | `Unrecognized key: "notifyUnknownThing"`                          | A key outside the 9-event catalog was submitted                                                                                | Remove the unsupported key, resubmit                        |
| 401    | `Missing merchantId in request context`                           | API Key authentication did not resolve a merchant                                                                              | Verify API Key headers and signature                        |
| 403    | `Not authorized to manage notification recipients for this store` | Merchant is not `owner` or `admin` of the store                                                                                | Verify the merchant's role on this store                    |
| 404    | `Notification recipient not found`                                | No recipient with that id on that store, or the sentinel id was sent after an explicit recipient already replaced the fallback | Re-read the list                                            |
| 409    | `Notification recipients changed concurrently, please retry`      | A concurrent write changed the list between read and write                                                                     | Re-read the list and retry                                  |
| 500    | `Internal server error`                                           | Unexpected server-side failure                                                                                                 | Retry with exponential backoff (start 5s, max 3 attempts)   |