受信者を更新 - Waffo Pancake

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

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

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 で拒否されます。

リクエスト例

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();

成功レスポンス (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": true
      },
      "createdAt": "2026-08-28T00:00:00.000Z"
    }
  }
}

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

レスポンスフィールド

フィールド	型	説明
`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 回）

⌘I