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

# クーポンエンドポイント

> クーポンと、購入者がチェックアウトで入力するコードの作成・管理

クーポンは割引の内容を定義します。割引はパーセンテージ、または通貨ごとの固定額で指定し、サブスクリプションの何回分の請求期間に適用するかも決めます。クーポンはそれぞれ自身の `code` を持ち（作成時に指定するか、Pancake に生成させます）、購入者はチェックアウトでそれを入力できます。同じ割引に対してコードを追加で配布したい場合は、[プロモーションコード](https://docs.waffo.ai/ja/api-reference/endpoints/promotion-codes/overview.md)を作成してください。クーポンと一緒に最大 20 個作成でき、後からいつでも追加できます。クーポンはチェックアウトセッションで ID（`couponId`）を指定して適用することもできます。クーポンの使用制限は有効期限と合計使用回数のみです。購入者の制限（購入者のメールアドレス、購入者ごとの回数、最低金額）はプロモーションコードに設定するため、クーポン自身のコードには制限がありません。

クーポンはストアに属し、1 つの環境にのみ存在します。`test` で作成したクーポンは `prod` には存在せず、その逆も同様です。

## クーポンのステータス値

| ステータス | 説明 |
| - | - |
| `active` | チェックアウトで使用可能 |
| `inactive` | 無効化済み。無効化は取り消せず、再度有効にすることはできません |
| `failed` | 作成失敗：決済プロバイダーがクーポンを拒否したか、作成を確認できませんでした。リクエストのコードはすべて解放済みです。クーポンを作成し直してください（同じコードを使用できます） |

## 割引ルール

| ルール | フィールド | 説明 |
| - | - | - |
| 割引 | `discount` | `percentage`（`percentOff`、0 \< x ≤ 100、小数第 2 位まで）または `fixed_amount`（通貨ごとの `amountOff`）。`amountOff` に含まれない通貨の注文には使用できません。為替換算は行いません |
| サブスクリプションでの適用期間 | `duration`、`durationInPeriods` | `once`（デフォルト）、`repeating`（`durationInPeriods` 回分の請求期間）、または `forever`。単発注文では 1 回のみ割引されます |
| 対象商品 | `productIds` | 指定した商品にのみ適用。空または省略時はストア全体が対象 |
| 有効期限 | `redeemBy` | この時刻を過ぎるとクーポンは使用できなくなり、サブスクリプションに適用済みの割引も終了します |
| 合計使用回数 | `maxRedemptions` | クーポンのコードとすべてのプロモーションコードを合計した使用回数の上限。返金しても回数は戻りません |

作成後に変更できるのは `name` のみです。割引内容を変えるには、新しいクーポンを作成し、古いクーポンを無効化してください。

## コード形式

クーポンとプロモーションコードには同じルールが適用されます：

| ルール | 詳細 |
| - | - |
| 文字 | 英字、数字、`-`。スペース、`_`、その他の記号は使用不可 |
| 長さ | 3–32 文字 |
| 大文字・小文字 | 区別しません。コードは大文字で保存・返却されます（`bf2026` は `BF2026` になります） |
| 一意性 | 同じストア・同じ環境の**有効な**コードの中で一意。クーポンとプロモーションコードで共通の範囲です |
| 再利用 | クーポンまたはプロモーションコードを無効化するとコードは即座に解放され、新しいクーポンやプロモーションコードで使用できます |

## 無効化

無効化は**取り消せません**。再有効化も削除もできません。クーポンを無効化すると、そのクーポンのプロモーションコードもすべて無効化され、それぞれのコードが解放されます。既存の注文には影響しません。サブスクリプションに適用済みの割引は、そのサブスクリプションの次回のプラン変更まで引き続き適用されます。

## 安全なリトライ

クーポンを作成するときは `X-Idempotency-Key` ヘッダー（SDK では `idempotencyKey` オプション）を送信し、リトライ時も同じキーを使ってください。キーなしでタイムアウト後にリトライしたとき `409` が返るのは、コード（`code` または `promotionCodes[].code`）を指定した場合だけです。最初のリクエストですでにクーポンが作成され、それらのコードが使用中になっているためです。コードを Pancake に生成させた場合、リトライするとクーポンがもう 1 つ作成されます。キーの要件は[エラー](https://docs.waffo.ai/ja/api-reference/errors.md)を参照してください。

## クーポンの取得

これらのエンドポイントは書き込み専用です。一覧と詳細は [GraphQL](https://docs.waffo.ai/ja/api-reference/endpoints/graphql/overview.md) で取得します。クーポンは `coupons`、`couponsCount`、`coupon(id)`、そのプロモーションコードは `promotionCodes` と `promotionCodesCount` を使用します。

```graphql theme={"system"}
query Coupons($storeId: String!) {
  coupons(storeId: $storeId, limit: 20, offset: 0, filter: { status: { eq: active } }) {
    id
    name
    code
    status
    timesRedeemed
    promotionCodesCount
  }
  couponsCount(storeId: $storeId, filter: { status: { eq: active } })
}
```

## エンドポイント

> **[クーポンの作成](https://docs.waffo.ai/ja/api-reference/endpoints/coupons/create-coupon.md)**
>
> クーポンとそのコードを作成し、必要に応じてプロモーションコードも同時に作成します。

> **[クーポンの更新](https://docs.waffo.ai/ja/api-reference/endpoints/coupons/update-coupon.md)**
>
> クーポン名を変更します。

> **[クーポンの無効化](https://docs.waffo.ai/ja/api-reference/endpoints/coupons/deactivate-coupon.md)**
>
> クーポンとそのすべてのプロモーションコードを完全に無効化します。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.