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

# Remove Recipient

> Remove an address from a store's merchant notification recipients

Remove a recipient from a store's recipient list. The address can be added again later.

```
POST /v1/actions/store-notification-recipient/remove-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 real recipient. The fallback entry's sentinel id returns 404 |

## Example Request

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://api.waffo.com/v1/actions/store-notification-recipient/remove-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"
    }'
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch(
    "https://api.waffo.com/v1/actions/store-notification-recipient/remove-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",
      }),
    },
  );

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

## Success Response (200)

```json theme={"system"}
{
  "data": {
    "recipientId": "11111111-2222-3333-4444-555555555555",
    "removed": true
  }
}
```

<Warning>
  Removing the last recipient returns 200 — there is no "keep at least one" guard. The store then falls back to the owner's account email, using the store-level `notify*` toggles.
  The fallback entry itself **cannot be removed**: it is not a stored row, so sending its `OWNER_<storeId>` sentinel id returns 404. To replace it, add a real recipient. Consumer-facing transactional email is a separate pipeline and keeps working.
</Warning>

## Response Fields

| Field         | Type    | Description                                                    |
| ------------- | ------- | -------------------------------------------------------------- |
| `recipientId` | string  | UUID of the removed recipient                                  |
| `removed`     | boolean | Always `true`; a miss returns 404 rather than `removed: false` |

## 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 |
| 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 id was the undeletable fallback sentinel | 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)   |