> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Coupon の設定と利用

> Coupon を有効化し、Merchant Portal で Promotion Code を設定して、API または Waffo Checkout から割引を適用します。

Coupon は割引ルールを定義します。Promotion Code は Coupon に紐づき、ユーザーまたは Merchant が使用する引換コードです。Merchant Portal で両方を設定し、API または Waffo Checkout から割引を適用できます。

<Info>
  Coupon は環境ごとに Waffo による有効化が必要です。連携を始める前に、Waffo の営業担当またはテクニカルサポートへ Merchant ID と対象環境を連絡してください。
</Info>

## 仕組み

```mermaid theme={null}
flowchart LR
  coupon["Coupon<br/>割引ルール"] --> code["Promotion Code<br/>ユーザー向け引換コード"]
  code --> result["Waffo Checkout または API<br/>割引を適用"]
  coupon -->|API で couponId を指定| result
```

## 対応範囲

| 範囲                 | 対応方法                                                                                      | 説明                                                                      |
| ------------------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `ONE_TIME_PAYMENT` | `POST /api/v1/order/create` の `promotionInfo`                                             | Merchant は `promotionCode` または `couponId` を指定できます                       |
| Waffo Checkout     | ユーザーが `promotionCode` を入力                                                                 | Coupon が有効で、注文作成時に Merchant が割引を事前適用していない 1 回払い注文で利用できます                |
| `SUBSCRIPTION`     | `POST /api/v1/subscription/create` と `POST /api/v1/subscription/change` の `promotionInfo` | Merchant は `promotionCode` または `couponId` を指定できます。割引期間は Coupon の設定に従います |
| Merchant Portal    | **Marketing → Coupons** と **Marketing → Promotion Codes**                                 | Coupon と Promotion Code を作成、表示、管理します                                    |

## Merchant Portal で設定する

<Steps>
  <Step title="Coupon を有効化する">
    Sandbox または Production の Merchant に対して Coupon を有効化するよう Waffo に依頼します。各環境を個別に確認してください。
  </Step>

  <Step title="Coupon を作成する">
    Merchant Portal にログインして **Marketing → Coupons** を開き、次の表に従って割引ルールと適用範囲を設定します。
  </Step>

  <Step title="Promotion Code を作成する">
    ユーザーに引換コードを入力させる場合は、Promotion Code を作成して Coupon に紐づけます。Coupon 詳細ページから作成するか、**Marketing → Promotion Codes** で 1 件または複数件を作成できます。
  </Step>

  <Step title="利用条件を設定する">
    必要に応じて利用回数、初回取引限定、最低注文金額、有効期限を設定して保存します。
  </Step>
</Steps>

| Coupon の設定             | ルール                                                                                             |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| Coupon Name            | ユーザーに表示されます。最大 40 文字です                                                                          |
| Percentage Off         | 1～100 を入力します。100% の場合、注文は無料になります                                                                |
| Fixed Amount Off       | 対応する通貨ごとに固定割引額を設定します。未設定の通貨では Coupon を使用できません                                                   |
| Duration               | `Once` は 1 回の決済、`Repeating` は指定した回数の Subscription 請求期間、`Forever` はすべての Subscription 請求期間に適用されます |
| Max Redemptions        | Coupon に紐づくすべての Promotion Code を通じた合計利用回数を制限します                                                 |
| Daily Redemption Limit | 同じユーザーが 1 日に利用できる回数を制限します                                                                       |
| Expiry Date            | 指定日時を過ぎた利用を拒否します                                                                                |
| Category Tags          | 対象商品を制限します。空欄の場合はすべての商品が対象です                                                                    |
| Metadata               | Merchant 独自の補足情報を保存します                                                                          |

Coupon の作成後は、割引タイプ、割引額、適用期間を変更できません。作成前に設定を確認してください。Coupon Name と Metadata は引き続き編集できます。利用を停止する場合は Coupon を無効化またはアーカイブします。

<Frame caption="対応する通貨ごとに固定割引額を設定します。">
  <img src="https://mintcdn.com/waffo-docs/xORaW9tAcq02K6Cd/images/developer-docs/use-cases/coupons/create-coupon-discount.png?fit=max&auto=format&n=xORaW9tAcq02K6Cd&q=85&s=043b9af59380de2f251b1227b9a2b07a" alt="Merchant Portal の Coupon 作成ページに表示された固定額割引、通貨別の金額、ライブプレビュー" width="2054" height="766" data-path="images/developer-docs/use-cases/coupons/create-coupon-discount.png" />
</Frame>

<Frame caption="適用期間によって、割引を 1 回、指定した請求期間、またはすべての Subscription 請求期間に適用します。">
  <img src="https://mintcdn.com/waffo-docs/xORaW9tAcq02K6Cd/images/developer-docs/use-cases/coupons/create-coupon-duration-limits.png?fit=max&auto=format&n=xORaW9tAcq02K6Cd&q=85&s=2f15dfa52cb80b604451d9b54d7b2be3" alt="Merchant Portal に表示された Coupon の適用期間、合計利用上限、ユーザーごとの日次上限、有効期限" width="2556" height="874" data-path="images/developer-docs/use-cases/coupons/create-coupon-duration-limits.png" />
</Frame>

**Marketing** メニューまたは作成ボタンが表示されない場合は、Merchant 管理者にアカウント権限の確認を依頼し、対象環境で Coupon が有効か Waffo に確認してください。Read-only アカウントは Marketing データを表示できますが、作成や編集はできません。

作成後は **Marketing → Discount Analytics** で、利用回数、割引額、注文あたりの平均割引額、利用率、推移を確認できます。Coupon ごとに結果を絞り込み、エクスポートできます。

## API から Coupon を適用する

`promotionInfo` では、次の相互排他的な 2 つのフィールドを使用できます。

| フィールド                         | 使用する場面                                           | 制限           |
| ----------------------------- | ------------------------------------------------ | ------------ |
| `promotionInfo.promotionCode` | Promotion Code を取得済みで、紐づく Coupon を適用する場合         | 文字列、最大 64 文字 |
| `promotionInfo.couponId`      | 特定の Coupon インスタンス ID を保持しており、その Coupon を直接適用する場合 | 文字列、最大 64 文字 |

1 回のリクエストでは一方だけを指定してください。`promotionCode` と `couponId` を同時に送信しないでください。

### 1 回払い

[`POST /api/v1/order/create`](/docs/api-reference/order-create/create-new-order) リクエストに `promotionInfo` を追加し、`promotionCode` または `couponId` のどちらか一方を指定します。

<Tabs>
  <Tab title="promotionCode">
    ```json theme={null}
    {
      "orderCurrency": "USD",
      "orderAmount": "100.00",
      "promotionInfo": {
        "promotionCode": "SAVE20"
      },
      "paymentInfo": {
        "productName": "ONE_TIME_PAYMENT"
      }
    }
    ```
  </Tab>

  <Tab title="couponId">
    ```json theme={null}
    {
      "orderCurrency": "USD",
      "orderAmount": "100.00",
      "promotionInfo": {
        "couponId": "coupon_123"
      },
      "paymentInfo": {
        "productName": "ONE_TIME_PAYMENT"
      }
    }
    ```
  </Tab>
</Tabs>

`orderAmount` は割引適用前の注文金額です。Coupon の検証後、Waffo が支払金額を再計算します。[`POST /api/v1/order/inquiry`](/docs/api-reference/order-inquiry/order-inquiry) のレスポンスでは、`originalAmount` が割引前の金額、`orderAmount` が割引後の Merchant 注文金額です。

### Subscription

[`POST /api/v1/subscription/create`](/docs/api-reference/subscription-create/create-subscription) または [`POST /api/v1/subscription/change`](/docs/api-reference/subscription-change/subscription-change) リクエストに `promotionInfo` を追加し、`promotionCode` または `couponId` のどちらか一方を指定します。

<Tabs>
  <Tab title="promotionCode">
    ```json theme={null}
    {
      "currency": "USD",
      "amount": "100.00",
      "promotionInfo": {
        "promotionCode": "SAVE20"
      }
    }
    ```
  </Tab>

  <Tab title="couponId">
    ```json theme={null}
    {
      "currency": "USD",
      "amount": "100.00",
      "promotionInfo": {
        "couponId": "coupon_123"
      }
    }
    ```
  </Tab>
</Tabs>

Coupon の適用期間によって、割引が 1 回のみ、指定した請求期間、または無期限に適用されるかが決まります。Stripe adapter は Stripe の Coupon または Promotion Code を Waffo にマッピングしません。割引を適用するには、Waffo のネイティブ Subscription API を呼び出して `promotionInfo` を指定してください。

## Waffo Checkout で Promotion Code を入力させる

ユーザー自身にコードを適用させる場合は、1 回払い注文の作成時に `promotionInfo` を省略します。ユーザーは `orderAction.webUrl` を開いた後、Checkout で Promotion Code を入力できます。

* Waffo は、Merchant で Coupon が有効で、注文作成時に割引が適用されていない場合にのみ入力欄を表示します。
* Checkout で入力できるのは Promotion Code です。`couponId` は入力できません。
* Waffo は Promotion Code を検証し、支払金額を再計算して表示します。
* 無効、期限切れ、利用条件外、または利用上限に達した Promotion Code は拒否されます。注文が通知なく定価で続行されることはありません。
* Merchant が API から Coupon を適用済みの場合、Checkout は割引後の金額を表示し、Promotion Code 入力欄を表示しません。

## 返金と決済結果

* 返金可能額の上限は割引後の Merchant 注文金額です。割引前の金額ではありません。
* Webhook または照会 API が返す最終ステータスを決済結果として扱ってください。ブラウザーのリダイレクトを決済成功の証明にしないでください。
* `promotionCode` または `couponId` を業務注文または Subscription とともに保存し、割引結果の照合と調査に利用してください。

## 受け入れチェックリスト

* Sandbox と対象 Production Merchant の両方で Coupon が有効になっています。
* 権限のあるアカウントで Merchant Portal の **Coupons** と **Promotion Codes** を開き、レコードを作成、表示できます。
* 1 回払いで `promotionCode` と `couponId` をそれぞれ使用した注文が成功し、各リクエストには一方のフィールドだけが含まれています。
* 割引を事前適用していない 1 回払い注文では、Checkout に有効な Promotion Code を入力でき、再計算後の金額が表示されます。
* 無効、期限切れ、または利用条件外の Promotion Code ではエラーが表示され、定価で続行されません。
* Subscription の作成または変更リクエストで Coupon が適用され、後続の請求期間は Coupon の適用期間設定に従います。
* Webhook または照会レスポンスで決済の最終ステータスを確認できます。1 回払いでは、`originalAmount` と `orderAmount` がそれぞれ割引前と割引後の金額に一致します。
* 返金額が割引後の Merchant 注文金額を超えていません。