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

# クーポンとプロモーションコード

> Waffo の割引エンジンの全体像：割合割引と定額割引のクーポン、Once / Repeating / Forever の期間、単一およびバッチのプロモーションコード、利用記録、割引分析、アカウントレベルの上限、サブスクリプションのトライアル、返金時の取り消し、2 つの API エントリポイント。

Waffo にはファーストパーティの割引エンジンがあります。**クーポン**（割引の内容）を定義し、**プロモーションコード**
（顧客が入力する、または貴社が配布する文字列）を発行し、その後 Portal から利用状況と割引支出を読み出します。
すべて **Marketing** メニューの下にあります：Coupons、Promotion Codes、Discount Analytics、Coupon Settings。
この機能は権限で制御されています。Portal に Marketing メニューが表示されていれば、貴社のアカウントで利用可能です。

## 割引そのものはどのように定義しますか？

| 割引タイプ | 設定内容 | 適用方法 |
| - | - | - |
| `PERCENT_OFF` | 1 つの整数の割合（1〜100） | どの通貨にも適用。100 にすると注文が無料になる |
| `AMOUNT_OFF` | **通貨ごと**の固定金額 | 設定した通貨にのみ適用 |

`AMOUNT_OFF` クーポンで設定されていない通貨は対象**外**です。その通貨の注文は、黙って全額請求されるのではなく
拒否されます。販売するすべての通貨を設定してください。

期間は**請求サイクル**で数えるため、サブスクリプションにのみ効きます。ワンタイム決済はいずれにせよ割引を 1 回消費します。
`ONCE` — 1 回の決済のみ。同じ割引に対する 2 回目の試行は拒否されます。`REPEATING` — N サイクル。
**Duration in Cycles** も設定します。`FOREVER` — すべてのサイクル。

## クーポン作成時に他に何を入力しますか？

| フィールド | 知っておくべきルール |
| - | - |
| **Coupon Name** | 顧客向けに表示され、Invoiceや領収書に記載されます。最大 40 文字 |
| **Max Redemptions** | このクーポンの**すべての**プロモーションコードを合わせた総利用回数。値を指定してください。作成リクエストは値を必要とします |
| **Daily Redemption Limit** | 任意。**顧客**ごと・1 日あたり。決済に顧客識別子が必要です |
| **Expiry Date**（`redeemBy`） | 任意。この日時以降はクーポンを利用できなくなります |
| **Category Tags**（`appliesTo`） | 任意。`goodsCategory` が一致する注文のみが対象。空はすべてを意味します |
| **Metadata** | 貴社自身の追跡用の自由なキー/値ペア。顧客には表示されません |

割引タイプ、割引値、期間は**作成後に変更できません**。送信前にページが警告を表示し、作成後は **Name** と
**Metadata** のみ編集可能です。**Deactivate** はそれ以降の利用を停止し、元に戻せます。**Archive** は元に戻せず、
そのクーポンのプロモーションコードも無効化します。いずれも、すでに適用された割引には影響しません。一覧には
生のステータスではなくライフサイクルタグが表示されます。優先順位はアーカイブ済み、次に期限切れ（`redeemBy` 経過）、
次にクーポン自身の状態です。

## プロモーションコードはどのように発行しますか？

| | 単一コード | バッチ |
| - | - | - |
| コード文字列 | 貴社が入力。英数字のみ、自動で大文字化、アカウント内で一意、**作成後は編集不可** | **プレフィックス**（英数字、最大 10 文字）から生成。例：`BFK2X9P`、`BFM7L3Q` |
| 数量 | 1 | 1 バッチあたり 1〜10,000 |
| 制限 | このコードの Max Redemptions、有効期限、First Time Only、通貨ごとの Minimum Amount | 同じ制限セットがバッチ内のすべてのコードに適用 |

バッチ作成は 4 ステップのウィザードです。クーポンを選び、プレフィックスと数量を設定し、制限を設定し、確定前に
サンプルコードと生成時間の見積もりを返す**プレビュー**を確認します。生成されたコードは永続的なので、
プレフィックスと数量を先に計画してください。バッチは非同期で実行されます。**Batch Tasks** には Task ID、クーポン、
ステータス（`PENDING` → `PROCESSING` → `SUCCESS` / `FAILED`）、成功件数、作成時刻が一覧表示され、
そのタスクが生成したコードへのリンクがあります。コードレベルの有効期限でクーポンの期限を延長することはできません。
クーポン自身の `redeemBy` は別途チェックされるため、2 つのうち早い方で利用が終了します。

## チェックアウトでコードが拒否されたのはなぜですか？

適用可否は金額計算の前に、おおむね次の順序で判定されます。

* **アカウントでクーポンが無効化**されている、またはクーポン設定がまだ存在しない。
* クーポンまたはコードが無効、期限切れ、または利用可能な在庫を使い切っている。もしくは、同じリクエストで渡された
  クーポンにそのコードが属していない。
* 注文金額がその通貨におけるコードの **Minimum Amount** 未満である、または `AMOUNT_OFF` に注文通貨の金額が
  設定されていない。
* 顧客ごとの制限、日次制限、または **First Time Only** が適用されるが、リクエストに**顧客識別子がない**。
  この場合、割引は無制限に適用されるのではなく拒否されます。
* **First Time Only** で、顧客にすでに完了した利用がある。これは貴社アカウント全体を範囲とし、このクーポン 1 つに
  限定されません。
* `ONCE` クーポンがすでに使用済み、または `REPEATING` クーポンがサイクルを使い切っている。

## 誰が何を利用したかはどこで確認できますか？

クーポン詳細ページには Overview、Promotion Codes、**Redemption History** タブがあります。各利用行には Record ID、
プロモーションコード、顧客、ソースタイプとソース ID、注文通貨での **Original / Discount / Final** 金額、ステータス、
作成時刻が含まれます。顧客、ソース ID、ステータス、日付範囲でフィルターし、フィルターしたビューをエクスポートできます。
ステータスは `CREATED`（予約済み、まだ確定していない）→ `COMPLETED`（確定。分析が集計する唯一の状態）、
または `VOIDED`（決済が完了せず、予約が解放された）/ `REVERSED`（返金後にロールバックされた）と遷移します。

## Discount Analytics はどのように計算されますか？

数値が貴社の集計と一致するかは 3 つの注意点で決まります。**完了した利用のみ**を集計するため、`CREATED`、
`VOIDED`、`REVERSED` は除外されます。金額は**通貨をまたいで換算なしで合計**されるため、カードとパフォーマンステーブルには
通貨記号のない生の数値が表示されます。通貨ごとの合計には利用記録のエクスポートを使用してください。また、
**Redemption Rate** = 完了した利用回数 ÷ 対象クーポンの Max Redemptions の合計であり、上限のないクーポンは分母に 0 を加えます。

デフォルトの範囲は直近 30 日間です。トレンドチャートは各利用の**確定**時刻を Portal のタイムゾーンで区切り、
Daily / Weekly / Monthly の切り替えで同じデータを再集約します。Coupon Performance は期間をクーポンごとに分割します：
Total Codes、Redemptions、Total Discount、Redemption Rate、Average Order Value。

## アカウントレベルのクーポン設定は何をしますか？

| 設定 | 効果 |
| - | - |
| **Enable Coupons** | マスタースイッチ。オフにすると、クーポンの内容にかかわらずすべての割引リクエストを拒否 |
| **Coupon Scope** | `SELF_ONLY` または `PLATFORM_WIDE` — 割引を自社マーチャントのみに限定するかどうか |
| **Max Active Coupons** | アカウントに記録された、同時に有効なクーポン数の上限 |
| **Max Discount Percent** | 利用時に `PERCENT_OFF` に上限を設けます。実効の割合はクーポンの値とこの上限の**低い方**です。50% の上限の下で 60% のクーポンは 50% 割引になります。拒否されるのではなく、黙って上限が適用されます |
| **Refund Reversal Strategy** | 下記参照 |

## 返金時、およびサブスクリプションのトライアル中、割引はどうなりますか？

**Full Reversal** 戦略では、**全額返金**によって利用が取り消されます。記録は `REVERSED` になり、利用枠はクーポンと
コードの両方に戻ります。**一部返金**では取り消され**ません**。記録は `COMPLETED` のままで、枠は消費されたままです。
完了しなかった決済は代わりに予約を `VOIDED` として解放します。取り消しは実際に消費された分のみを返すため、
実際の割引を受けていないサイクルがカウンターをマイナスにすることはありません。

金額ゼロのトライアル期間は、クーポンとコードの**その期間の利用枠を占有**しますが、割引自身のライフサイクル回数は
消費し**ません**。したがって、無料トライアル付きサブスクリプションの `ONCE` クーポンは、最初の有料サイクルに対して
1 回の実際の割引を依然として利用できます。サブスクリプション以外では、実際に割引が適用されていない金額ゼロの注文は
何も消費しません。

## API 経由で割引を適用するにはどうすればよいですか？

注文作成には `promotionInfo` オブジェクトがあり、相互排他の 2 つのフィールド（各最大 64 文字）を持ちます。
`promotionInfo.promotionCode` は貴社または Waffo ホスト型チェックアウトページが使用します。チェックアウトの割引入力欄は
**プロモーションコードのみ**を受け付けるため、顧客がクーポン ID を入力することはありません。`promotionInfo.couponId` は
貴社専用で、注文作成時にコードを介さず特定のクーポンを適用します。どちらか一方のみを渡し、両方は渡さないでください。
コードとクーポン ID の両方が届いた場合、コードはそのクーポンに属している必要があります。注文作成のフィールドレベルの
ルールとチェックアウトページ自体の動作は、注文作成フィールドガイドとチェックアウトページのドキュメントで扱っています。

## Marketing ページから何をエクスポートできますか？

Marketing ページで管理するものはすべて Portal の機能です。クーポンの作成・編集・無効化・アーカイブ、単一コードと
コードバッチの作成、利用記録と分析の閲覧のいずれについても、API キーで署名する連携エンドポイントは存在しません。
唯一の API 接点は、上記の注文作成時の `promotionInfo` です。

4 つの一覧に **Export** ボタンがあります：Coupons、Promotion Codes、Redemption History、Discount Analytics。
各エクスポートはタスクとして実行され、`<type>-<task-id>.csv` という名前の CSV を提供します。プレフィックスは
`coupon`、`promotion-code`、`promotion-record`、`promotion-analytics` です。エクスポートは画面上のフィルターを尊重し、
最大 10,000 行を対象とします。一覧とエクスポートのタイムスタンプは Portal のタイムゾーンで表示されます。
Portal はリクエストとともにそのオフセットを送信します。

***

数値が合いませんか？ クーポン ID、プロモーションコード、または利用記録の Record ID を添えて
[サポートにお問い合わせください](mailto:support@waffo.com)。


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