Update Recipient

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.

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.

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

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 }
  }'

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();

Success Response (200)

{
  "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"
    }
  }
}

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

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)

Overview

Auth

Merchant API (API Key)

Customer Portal API (Session Token)

GraphQL

Request Body

Example Request

Success Response (200)

Response Fields

Errors

​Request Body

​Example Request

​Success Response (200)

​Response Fields

​Errors

Request Body

Example Request

Success Response (200)

Response Fields

Errors