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

# Notification Recipient Endpoints

> Manage who receives merchant notification emails for a store

Merchant notifications — new order, new subscription, renewal, cancellation, past due — are delivered to the recipients configured on the store. Each recipient has its own address and its own per-event subscription toggles, so two people on the same store can subscribe to different things. When a store has no recipients configured, notifications fall back to the store owner's account email.

## Event catalog

| Toggle                          | Fires on                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------ |
| `notifyNewOrders`               | A new one-time order was placed (also covers the first-sale celebration email) |
| `notifyNewSubscriptions`        | A new subscription was activated                                               |
| `notifySubscriptionCanceled`    | A subscriber canceled but the access period is still running                   |
| `notifySubscriptionRenewed`     | A subscription renewal was charged successfully                                |
| `notifySubscriptionEnded`       | A subscription fully ended and access was revoked                              |
| `notifySubscriptionPastDue`     | A subscription renewal failed and the subscription is past due                 |
| `notifySubscriptionUncanceled`  | A subscriber reverted a pending cancellation                                   |
| `notifySubscriptionPlanChanged` | A subscription plan change took effect                                         |
| `notifyChargeback`              | A payment was disputed by the cardholder                                       |

<Note>
  All nine toggles above are **per recipient** — including `notifySubscriptionPlanChanged` and `notifyChargeback`. Two people on the same store can subscribe to different events, and `update-recipient` accepts any of the nine.

  The delivery **address** follows the recipient list: merchant notifications go to the configured recipients, falling back to the store owner's account email while the list is empty, rather than to `supportEmail`.
</Note>

## Limits

Each store may have at most **5 recipients**. Exceeding the limit returns 400. There is no lower bound — but an empty list does not mean silence: it falls back to the store owner's account email (see below). Consumer-facing transactional email (order receipts, subscription confirmations) is a separate pipeline and is unaffected.

## The fallback recipient

While a store has no explicit recipients, the list contains exactly one synthesized entry with `isPrimary: true`: the address is the store owner's account email, the toggles come from the store-level `notify*` settings, and `createdAt` is the store's creation time. Its `id` is a stable sentinel of the form `OWNER_<storeId>`.

It is **not a stored row**. `remove-recipient` on that id returns 404 — the account email is the fallback and cannot be deleted; add a real recipient to replace it. `update-recipient` on that id **materializes** it instead: the account email is written as a real recipient, your patch is applied on top, and the response carries a real UUID.

Adding the first explicit recipient makes the fallback entry disappear. That is intentional and visible.

## Environments

Recipients are **not environment-scoped**. Requests may carry `X-Environment` as usual, but it does not filter or shape recipient reads and writes — the same store returns the same list in `test` and in `prod`.

## Listing recipients

There is no `list-recipients` endpoint — querying the recipient list goes through the top-level GraphQL query `storeNotificationRecipients`, which also returns the fallback entry when no explicit recipient is configured:

```graphql theme={"system"}
query GetStoreNotificationRecipients($storeId: String!) {
  storeNotificationRecipients(storeId: $storeId, limit: 10, offset: 0) {
    id
    email
    isPrimary
    createdAt
    preferences {
      notifyNewOrders
      notifyNewSubscriptions
      notifySubscriptionCanceled
      notifySubscriptionRenewed
      notifySubscriptionEnded
      notifySubscriptionPastDue
      notifySubscriptionUncanceled
      notifySubscriptionPlanChanged
      notifyChargeback
    }
  }
}
```

## Endpoints

<CardGroup cols={3}>
  <Card title="Add Recipient" icon="plus" href="/api-reference/endpoints/notification-recipients/add-recipient">
    Add an address that receives merchant notifications.
  </Card>

  <Card title="Update Recipient" icon="pen" href="/api-reference/endpoints/notification-recipients/update-recipient">
    Change which events a recipient subscribes to.
  </Card>

  <Card title="Remove Recipient" icon="trash" href="/api-reference/endpoints/notification-recipients/remove-recipient">
    Remove a recipient from the list.
  </Card>
</CardGroup>