Add Recipient

Add a merchant notification recipient to a store. Each store can have up to 5 recipients. A new recipient’s 10 event toggles inherit the store’s current notify* settings (any key the store never set counts as subscribed), and isPrimary is always false. An event you already turned off therefore stays off — adding a recipient never resumes it. Inheritance happens once, at creation: all 10 keys are written at that moment, so later changes to the store’s notify* no longer affect existing recipients — use update-recipient instead. For the same reason, a second recipient inherits the store’s current values rather than the first recipient’s choices, and re-adding a removed address is a fresh inheritance, not a restore.

A new store is seeded with one real recipient — the merchant account email, marked isPrimary: true. Recipients added here are appended alongside it; nothing is ever synthesized on the fly. Remove every recipient and the store sends no merchant notifications at all — there is no fallback address.

POST /v1/actions/store-notification-recipient/add-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`)
`email`	string	Yes	Recipient address. Normalized with `lower(trim())` before storage, so addresses differing only by case or surrounding whitespace count as the same recipient.

Example Request

curl -X POST https://api.waffo.com/v1/actions/store-notification-recipient/add-recipient \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $WAFFO_MERCHANT_ID" \
  -H "X-Signature: ..." \
  -d '{
    "storeId": "STO_2aUyqjCzEIiEcYMKj7TZtw",
    "email": "ops@acme.com"
  }'

const response = await fetch(
  "https://api.waffo.com/v1/actions/store-notification-recipient/add-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",
      email: "ops@acme.com",
    }),
  },
);

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": true,
        "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 returned recipient.id is a UUID, not a Short ID. Treat it as an opaque string and pass it back as recipientId to update-recipient and remove-recipient.

Response Fields

Field	Type	Description
`id`	string	Recipient UUID. Pass it back verbatim to `update-recipient` / `remove-recipient`
`storeId`	string	Owning store Short ID
`email`	string	Normalized recipient address
`isPrimary`	boolean	`false` for every recipient added through this endpoint; only the row seeded at store creation is `true`. Provenance only — it carries no privilege and is removable like any other
`preferences`	object	The 10 event toggles, inherited from the store’s current `notify*` at creation
`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: storeId`	`storeId` was not provided	Fix the request body, resubmit
400	`Expected format: STO_xxx, got "..."`	`storeId` Short ID could not be decoded	Fix the `storeId` format, resubmit
400	`Invalid email format`	`email` is not a valid address	Fix the address, resubmit
400	`Notification recipient limit reached (max 5 per store)`	Store already has 5 recipients	Remove an existing recipient first
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
409	`Recipient with this email already exists for this store`	The normalized address is already a recipient, or a concurrent write won the race	Update the existing recipient instead of adding a duplicate
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