Update Recipient - Waffo Pancake

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.

recipientId must be the UUID of a recipient already stored on that store — including the row seeded at store creation, which is editable like any other. Anything that is not a UUID is rejected with 400; a well-formed UUID that is not on the store returns 404. Nothing is materialized or synthesized by this endpoint.

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	UUID of a stored recipient, passed back verbatim from `add-recipient` or the GraphQL query
`preferences`	object	Yes	The toggles to change. Only the 10 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": false,
        "notifyRefundSucceeded": 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	Taken from the stored entry: `true` when the row you patched is the one seeded at store creation, `false` otherwise
`preferences`	object	The 10 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 not a UUID	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 — it was never added, or a concurrent write removed it	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)

⌘I