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

# プロモーションコードエンドポイント

> クーポンに対して、それぞれ独自の制限を持つプロモーションコードを追加で配布する

プロモーションコードは、既存の[クーポン](https://docs.waffo.ai/ja/api-reference/endpoints/coupons/overview.md)に対して購入者が入力できる別のコードです。クーポンの割引が適用されます。クーポンの制限は有効期限と合計使用回数のみで、購入者の制限はプロモーションコードごとに設定します。インフルエンサーやキャンペーンごとのコード、使い切りコードの一括発行などに利用できます。

プロモーションコードは `active` のクーポンに対してのみ作成でき、クーポンと同じストア・同じ環境に属します。プロモーションコードを作成しても、クーポンの割引内容は変わりません。

## プロモーションコードのステータス値

| ステータス | 説明 |
| - | - |
| `active` | クーポンが `active` の間、チェックアウトで使用可能 |
| `inactive` | 無効化済み。無効化は取り消せず、再度有効にすることはできません |

## 制限

プロモーションコードはそれぞれ独自の購入者制限を持ちます。クーポンの `redeemBy` と `maxRedemptions` もすべてのコードに適用されます：

| フィールド | 説明 |
| - | - |
| `customerEmails` | 指定した購入者のみ（最大 100 件のメールアドレス、大文字・小文字を区別しない） |
| `perCustomerLimit` | 購入者ごとの累計使用回数 |
| `maxRedemptions` | このプロモーションコードの使用回数。クーポンの `maxRedemptions` を超えることはできず、クーポン側の上限も同時に適用されます |
| `expiresAt` | 有効期限。クーポンの `redeemBy` より後にはできません。省略時はクーポンの `redeemBy` を引き継ぎます |
| `minimumAmount` | 通貨ごとの最低注文金額（割引前・税抜で判定）。例：`{ "USD": "50.00" }`。指定のない通貨には最低金額なし |

プロモーションコードはクーポンと一緒に作成するか（[クーポンの作成](https://docs.waffo.ai/ja/api-reference/endpoints/coupons/create-coupon.md)、最大 20 個）、以下のエンドポイントで 1 つずつ、または一括で作成します。クーポン自身の `code` はプロモーションコードには含まれません。独自の制限はなく、`promotionCodes` では返されず、クーポンと一緒にのみ無効化できます。

## コード

プロモーションコードはクーポンと同じ[コード形式](https://docs.waffo.ai/ja/api-reference/endpoints/coupons/overview.md)に従います。英字・数字・`-` の 3–32 文字で、大文字・小文字を区別せず大文字で保存され、同じストア・同じ環境の有効なコードの中で一意であり、無効化すると解放されます。`code` を省略した場合や一括生成の場合、ランダム部分は大文字の英字と数字で構成され、紛らわしい `0`、`O`、`1`、`I`、`L` は使用されません。

## 安全なリトライ

`X-Idempotency-Key` ヘッダー（SDK では `idempotencyKey` オプション）を送信し、リトライ時も同じキーを使ってください。特に[プロモーションコードの一括生成](https://docs.waffo.ai/ja/api-reference/endpoints/promotion-codes/generate-promotion-codes.md)では重要です。コードはランダムに生成されるため、キーなしでリトライすると 2 つ目のバッチが生成されます。キーの要件は[エラー](https://docs.waffo.ai/ja/api-reference/errors.md)を参照してください。

## プロモーションコードの取得

これらのエンドポイントは書き込み専用です。クーポンのプロモーションコードは [GraphQL](https://docs.waffo.ai/ja/api-reference/endpoints/graphql/overview.md) の `promotionCodes` と `promotionCodesCount` で取得します。`batchId` で絞り込むと、生成したバッチを再取得できます。

```graphql theme={"system"}
query PromotionCodes($couponId: String!) {
  promotionCodes(couponId: $couponId, limit: 50, offset: 0) {
    id
    code
    status
    batchId
    timesRedeemed
  }
  promotionCodesCount(couponId: $couponId)
}
```

## エンドポイント

> **[プロモーションコードの作成](https://docs.waffo.ai/ja/api-reference/endpoints/promotion-codes/create-promotion-code.md)**
>
> クーポンにプロモーションコードを 1 つ追加します。

> **[プロモーションコードの一括生成](https://docs.waffo.ai/ja/api-reference/endpoints/promotion-codes/generate-promotion-codes.md)**
>
> 1 回の呼び出しで 1–500 個のランダムなプロモーションコードを生成します。

> **[プロモーションコードの無効化](https://docs.waffo.ai/ja/api-reference/endpoints/promotion-codes/deactivate-promotion-code.md)**
>
> プロモーションコードを完全に無効化し、コードを解放します。


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