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

# 受信者を更新

> 受信者が購読するマーチャント通知イベントを変更する

受信者のイベント購読を更新します。更新は**部分更新**です：変更するトグルだけを送信すれば、省略したキーは現在の値を保ちます。レスポンスは常にマージ後の完全なオブジェクトを返します。

<Note>
  明示的な受信者が 1 件もない間、リストに含まれるフォールバックエントリ（`isPrimary: true`、オーナーのアカウントメール）の `id` は `OWNER_<storeId>` 形式のセンチネル値です。その id を本エンドポイントに渡すと**その場で実体化**されます：アカウントメールが実在の受信者になり、パッチがストアレベルの `notify*` トグルの上に適用され、レスポンスは実際の UUID を返します。フォールバックエントリはその後消えます。
</Note>

```
POST /v1/actions/store-notification-recipient/update-recipient
```

**認証：** API Key（owner または admin ロールが必要）

## リクエストボディ

| フィールド         | 型      | 必須 | 説明                                                                                                 |
| ------------- | ------ | -- | -------------------------------------------------------------------------------------------------- |
| `storeId`     | string | はい | ストア ID（Short ID 形式 `STO_xxx`）                                                                      |
| `recipientId` | string | はい | `add-recipient` または GraphQL クエリの戻り値をそのまま渡します —— 実在の受信者は UUID、フォールバックエントリは `OWNER_<storeId>` センチネル値 |
| `preferences` | object | はい | 変更するトグル。イベントカタログの 9 キーのみ受け付け、それ以外は 400 で拒否されます。                                                    |

## リクエスト例

<CodeGroup>
  ```bash cURL theme={"system"}
  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 }
    }'
  ```

  ```javascript JavaScript theme={"system"}
  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();
  ```
</CodeGroup>

## 成功レスポンス (200)

```json theme={"system"}
{
  "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"
    }
  }
}
```

<Note>
  メールアドレス自体は変更できません。通知先を別のアドレスに移すには、新しい受信者を追加してから古い方を削除してください。
</Note>

## レスポンスフィールド

| フィールド         | 型       | 説明                                          |
| ------------- | ------- | ------------------------------------------- |
| `id`          | string  | 受信者 UUID                                    |
| `storeId`     | string  | 所属ストアの Short ID                             |
| `email`       | string  | 正規化された受信アドレス（本エンドポイントでは変更されません）             |
| `isPrimary`   | boolean | ここでは常に `false` —— フォールバックの実体化により実在の受信者になります |
| `preferences` | object  | パッチをマージした後の 9 つのイベントトグル                     |
| `createdAt`   | string  | 作成日時（ISO 8601）                              |

## エラー

> **リトライ方針：** 4xx は決してリトライしないでください —— リクエストを修正して再送します。5xx は指数バックオフでリトライします（初回 5 秒、最大 3 回）。

| ステータス | `errors[0].message`                                               | 意味                                                          | 推奨対応                                      |
| ----- | ----------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------- |
| 400   | `Missing required field: recipientId`                             | `recipientId` が未指定                                          | リクエストボディを修正して再送                           |
| 400   | `Invalid recipient id format: expected UUID, got "..."`           | `recipientId` が UUID でも当ストアのセンチネル値でもない                      | add-recipient や GraphQL が返した `id` をそのまま渡す |
| 400   | `Unrecognized key: "notifyUnknownThing"`                          | 9 イベントのカタログ外のキーを送信した                                        | 未対応のキーを削除して再送信                            |
| 401   | `Missing merchantId in request context`                           | API Key 認証でマーチャントを解決できなかった                                  | API Key のヘッダーと署名を確認                       |
| 403   | `Not authorized to manage notification recipients for this store` | マーチャントがそのストアの `owner` / `admin` ではない                        | ストアにおけるマーチャントのロールを確認                      |
| 404   | `Notification recipient not found`                                | そのストアに該当 id の受信者がない、または実在の受信者がフォールバックを置き換えた後にセンチネル id が送られた | リストを取得し直す                                 |
| 409   | `Notification recipients changed concurrently, please retry`      | 読み取りと書き込みの間に並行書き込みがリストを変更                                   | リストを取得し直して再試行                             |
| 500   | `Internal server error`                                           | サーバー側の予期しない障害                                               | 指数バックオフでリトライ（初回 5 秒、最大 3 回）               |