受信者を追加

ストアにマーチャント通知の受信者を追加します。各ストアの受信者は最大 5 件です。新規受信者の 9 つのイベントトグルはストア側の現在の notify* 設定を継承し（ストアが未設定のキーは購読として扱われます）、isPrimary は常に false です。既にオフにしたイベントが、受信者の追加によって再開することはありません。継承が起きるのは作成時の一度だけです：9 つのキーはその時点で書き込まれるため、以降ストアの notify* を変更しても既存の受信者には反映されません（変更は update-recipient で行います）。同様に、2 人目の受信者は 1 人目の選択ではなくストアの現在値を継承し、削除したアドレスを再追加した場合も以前の設定の復元ではなく新たな継承になります。

明示的な受信者が 1 件もない間、リストには合成されたフォールバックエントリ（isPrimary: true）が表示され、アドレスはストアオーナーのアカウントメールで、通知もそこへ届きます。最初の明示的な受信者を追加するとそのフォールバックは消えます —— 以降は設定されたアドレスのみが通知を受け取ります。

POST /v1/actions/store-notification-recipient/add-recipient

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

リクエストボディ

フィールド	型	必須	説明
`storeId`	string	はい	ストア ID（Short ID 形式 `STO_xxx`）
`email`	string	はい	受信アドレス。保存前に `lower(trim())` で正規化されるため、大文字小文字や前後の空白だけが異なるアドレスは同一の受信者として扱われます。

リクエスト例

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

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

返される recipient.id は Short ID ではなく UUID です。不透明な文字列として扱い、update-recipient と remove-recipient の recipientId にそのまま渡してください。

レスポンスフィールド

フィールド	型	説明
`id`	string	受信者 UUID。フォールバックエントリは `OWNER_<storeId>` 形式のセンチネル値を使います
`storeId`	string	所属ストアの Short ID
`email`	string	正規化された受信アドレス
`isPrimary`	boolean	本エンドポイントで追加した受信者は常に `false`。合成されたフォールバックエントリのみが `true`
`preferences`	object	9 つのイベントトグル。作成時にストアの現在の `notify*` を継承
`createdAt`	string	作成日時（ISO 8601）

エラー

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

ステータス	`errors[0].message`	意味	推奨対応
400	`Missing required field: storeId`	`storeId` が未指定	リクエストボディを修正して再送
400	`Expected format: STO_xxx, got "..."`	`storeId` の Short ID をデコードできない	`storeId` の形式を修正して再送
400	`Invalid email format`	`email` が正しいアドレスではない	アドレスを修正して再送
400	`Notification recipient limit reached (max 5 per store)`	ストアに既に 5 件の受信者がある	既存の受信者を先に削除
401	`Missing merchantId in request context`	API Key 認証でマーチャントを解決できなかった	API Key のヘッダーと署名を確認
403	`Not authorized to manage notification recipients for this store`	マーチャントがそのストアの `owner` / `admin` ではない	ストアにおけるマーチャントのロールを確認
409	`Recipient with this email already exists for this store`	正規化後のアドレスが既に受信者として存在、または並行書き込みが先行	重複追加せず既存の受信者を更新
500	`Internal server error`	サーバー側の予期しない障害	指数バックオフでリトライ（初回 5 秒、最大 3 回）

概要

認証

マーチャント API（API Key）

Customer Portal API（Session Token）

GraphQL

リクエストボディ

リクエスト例

成功レスポンス (200)

レスポンスフィールド

エラー

​リクエストボディ

​リクエスト例

​成功レスポンス (200)

​レスポンスフィールド

​エラー

リクエストボディ

リクエスト例

成功レスポンス (200)

レスポンスフィールド

エラー