割引とプロモーション

​

できること

• クーポンを作成：パーセンテージまたは固定額の割引に、対象商品、合計使用回数、有効期限を設定。購入者がチェックアウトで入力するコードを持ちます
• 同じクーポンにプロモーションコードを追加発行し、コードごとに独自の購入者制限を設定（対象メールアドレス、購入者ごとの回数、最低金額）—— インフルエンサーやキャンペーンチャネルごとのコード、使い切りコードの一括発行など
• 購入者がチェックアウトページでコードを入力する、コード適用済みの商品リンクを共有する、またはチェックアウトセッション作成時にサーバーからクーポンを適用したりプロモーションコードを事前入力したりする

​

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

​

クーポンの作成

​

Dashboard 経由

​

API または SDK 経由

import { CouponDiscountType, WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

const { coupon } = await client.coupons.create(
  {
    storeId: "STO_xxx",
    name: "Spring sale",
    discount: { type: CouponDiscountType.Percentage, percentOff: 20 },
    maxRedemptions: 500,
    code: "SPRING-20", // the coupon's own code; omit it for a random one
    // Promotion codes created together with the coupon (up to 20), each with its own restrictions
    promotionCodes: [{ code: "SPRING-NEW", restrictions: { perCustomerLimit: 1 } }],
  },
  { idempotencyKey: "coupon-spring-2026" },
);

// A code for one influencer: 100 uses, at least $50 before tax
await client.promotionCodes.create({
  couponId: coupon.id,
  code: "KOL-ALICE",
  restrictions: { maxRedemptions: 100, minimumAmount: { USD: "50.00" } },
});

res, err := client.Coupons.Create(ctx, pancake.CreateCouponParams{
    StoreID:        "STO_xxx",
    Name:           "Spring sale",
    Discount:       pancake.CouponDiscount{Type: pancake.CouponDiscountTypePercentage, PercentOff: pancake.Ptr(20.0)},
    MaxRedemptions: pancake.Ptr(500),
    Code:           pancake.Ptr("SPRING-20"),
    PromotionCodes: []pancake.CreateCouponPromotionCodeParams{{
        Code:         pancake.Ptr("SPRING-NEW"),
        Restrictions: &pancake.PromotionCodeRestrictions{PerCustomerLimit: pancake.Ptr(1)},
    }},
}, pancake.WithIdempotencyKey("coupon-spring-2026"))

​

よくあるキャンペーン

await client.coupons.create({
  storeId: "STO_xxx",
  name: "Launch sale",
  code: "LAUNCH-20",
  discount: { type: CouponDiscountType.Percentage, percentOff: 20 },
  maxRedemptions: 500,
  redeemBy: "2026-11-15T00:00:00.000Z",
});

await client.promotionCodes.create({
  couponId: "CPN_xxx",
  code: "KOL-ALICE",
  restrictions: { maxRedemptions: 200, minimumAmount: { USD: "30.00" } },
});

const { promotionCodes } = await client.promotionCodes.generate({
  couponId: "CPN_xxx",
  count: 500,
  prefix: "NEWS-",
  restrictions: { maxRedemptions: 1 },
});

await client.promotionCodes.create({
  couponId: "CPN_xxx",
  code: "COMEBACK-30",
  restrictions: { customerEmails: ["jane.doe@example.com"], perCustomerLimit: 1 },
});

// サーバーコード。購入者のランクを確認してから
const session = await client.checkout.createSession({
  storeId: "STO_xxx",
  productId: "PROD_xxx",
  currency: "USD",
  couponId: tier === "gold" ? "CPN_gold" : undefined,
  buyerEmail: customer.email,
});
redirect(session.checkoutUrl);

await client.coupons.create({
  storeId: "STO_xxx",
  name: "Annual upgrade",
  code: "GO-ANNUAL",
  discount: { type: CouponDiscountType.Percentage, percentOff: 25 },
  duration: CouponDuration.Repeating,
  durationInPeriods: 3,
  productIds: ["PROD_annual"],
});

​

チェックアウトでの割引の適用

​

コード入力欄

const session = await client.checkout.createSession({
  productId: "PROD_xxx",
  currency: "USD",
  allowPromotionCodes: true,
});

​

よくあるシナリオ

​

コード付き商品リンク

https://pancake.waffo.ai/store/{store-slug}/product/{productId}?currency=USD&discount_code=SPRING-20

​

サーバーで指定したクーポン

const session = await client.checkout.authenticated.create({
  productId: "PROD_xxx",
  currency: "USD",
  buyerIdentity: "userIdInYourSystem",
  couponId: "CPN_xxx",
});

​

サーバーで事前入力したプロモーションコード

const session = await client.checkout.createSession({
  productId: "PROD_xxx",
  currency: "USD",
  promotionCode: "KOL-ALICE",
  allowPromotionCodes: true, // let the customer replace or remove it
});

​

コードが使えない場合

• ゲストのチェックアウトでは、入力時の合計使用回数には支払い済みの注文だけを数え、支払い済みの回数が上限に達したときにだけ拒否します。未払いの注文と購入者ごとの回数は注文時に判定します。残りの枠を他の購入者の未払い注文が使っている場合は、注文時に拒否されます。
• ログイン済みの購入者が同じコードで作成した自分の未払い注文は、使用回数に数えません。ただし、まだ使用枠を確保している未払いのプラン変更は除きます —— 確定済みで切り替え日を待っている変更、または現在の割引が引き継がれる先の変更です。
• 購入者が支払いページを離れて未払いのまま戻ってきても、同じコードをもう一度入力できます。新しい注文を確定すると、未払い注文が使っていた枠を新しい注文が引き継ぎます。

​

サブスクリプション

​

割引される期間の数

​

トライアル

​

使用回数が加算されるとき

• 割引される最初の請求が成功したときに 1 回加算されます：最初の有料の請求、有料トライアルではトライアルの請求です。以降の更新では加算されません。
• それまではサブスクリプションが使用枠を確保しています。その請求の前にサブスクリプションが終了した場合 —— 無料トライアル中のキャンセル、または初回の支払いが成功しなかった場合 —— 使用枠は戻り、購入者は再びコードを使えます。72 時間を超えて未払いのサブスクリプション注文はキャンセルされませんが、使用枠は確保しなくなります：同じクーポンを使う次の注文（そのクーポンのどのプロモーションコードでも）がその枠を取り戻します。
• その請求の前にクーポンの有効期限が過ぎ、通常価格で請求された場合も、使用枠は戻ります。
• 同じ購入者が同じコードで新しい注文を作成したときに引き継がれるのは、一度も支払われていない以前の注文の使用枠だけです。無料トライアル中の有効なサブスクリプションは使用枠を確保したままです：新しい注文には引き継がれず、確保中の枠はコードの回数制限に数えられます。

​

割引が終わるとき

• 適用期間が終わると、更新は通常価格で請求されます。
• クーポンの有効期限は、サブスクリプションに適用済みの割引も終了させます：期限後の更新は forever でも通常価格で請求されます。プロモーションコード自体の有効期限は、新しい使用を止めるだけです。
• クーポンを無効化しても、サブスクリプションに適用済みの割引は次回のプラン変更まで終了しません —— プラン変更を参照してください。
• サブスクリプションをキャンセルすると割引は完全に失効します。期間終了前にキャンセルを取り消した場合、割引はそのまま続きます。
• プラン変更では、割引が新しいプランに引き継がれない限り割引は終了します —— プラン変更を参照してください。

​

プラン変更

• 第 1 期。 即時に適用される変更では、新しいサブスクリプションの第 1 期の金額は、新しいプランの価格から当期の未使用分のクレジットを引いた額 —— または changeAmount / changeCreditAmount で指定した金額 —— です。これが 0 より大きければ割引が適用され、1 期間を消費します。割引は新しいプランの全額で計算し、そのあとで元のプランの残りのクレジットを差し引きます：パーセント割引は新しいプランの価格に対する割合、定額割引は同じ金額で、割引額は第 1 期の金額が上限です。購入者の支払いは第 1 期の金額から割引を引いた額で、0 を下回りません。割引が第 1 期の金額全体をカバーする場合も 1 期間を消費します。0 の場合 —— 多くはクレジットが新しいプランの価格以上になるダウングレード —— 割引は適用されず期間も消費せず、割引は第 2 期から始まります。次の期間から適用される変更は通常価格の期間から始まり、トライアルを付与する変更は上記のトライアルのルールに従います。
• クレジットは購入者が支払う金額に基づきます。 当期の未使用分のクレジットは、その期間に購入者が支払う金額から計算されます：その期間が割引されていれば割引後の金額、そうでなければ表示価格です。
• プロモーションコードの最低金額は、新しいプランの通常価格（割引前・税抜）で判定します。クレジットは差し引きません。
• 使用回数が加算されるとき。 新しいコードは、新しいサブスクリプションで割引される最初の請求が成功したときに加算されます —— 第 1 期、または第 1 期が 0 の場合は第 2 期です。変更が完了しなかった場合 —— 購入者が完了しなかった、決済チャネルが失敗を報告した、次の期間から適用される変更がキャンセルされた —— 使用枠は戻ります。開始されたまま完了しない変更は、72 時間後に使用枠を確保しなくなり、同じクーポンを使う次の注文（そのクーポンのどのプロモーションコードでも）がその枠を取り戻します —— すでに終了したサブスクリプションからその変更へ引き継がれる途中の枠も同様です。現在のサブスクリプション自身のコードが割引される最初の請求をまだ待っている場合、引き継がれる割引はその確保中の枠を新しいサブスクリプションに移します。新しいコードまたはコードなしの場合、その枠は戻ります。

​

サブスクリプションの支払い金額

• サブスクリプションの注文には表示価格が記録されます。各支払いには、その期間について Pancake が想定する金額 —— 元の価格、割引額、支払額 —— が記録されます。subscription.payment_succeeded webhook は listPrice にこれらの金額（listTotal、discountAmount、total）を含めます。
• 請求額が想定した割引と一致しない場合 —— 割引が早く終了した、または多く・少なく請求された場合 —— Pancake が内部で照合します。支払いには想定金額が記録されたままで、実際の請求額は webhook の chargedAmount にあります。
• 初回の領収書 —— 有料トライアルではトライアルの請求、トライアルなしでは最初の請求 —— には、その請求が割引される場合、元の価格、割引、小計、税額、支払額が表示されます。無料トライアルの初回の領収書は $0 で、内訳は表示されません。
• 各更新の領収書にも、その期間が割引される場合は同じ内訳が表示されます。トライアル終了後の最初の請求では更新の領収書は送られません —— 無料トライアルでは、これがまさに割引される期間です。購入者は請求予定の通知でその想定金額を確認できます。
• メールに表示される次回の請求額は、次の期間も割引される場合にのみ割引が反映されます。
• プラン変更後、新しいサブスクリプションの最初の支払いは第 1 期の金額を想定として記録します（プラン変更を参照）が、この支払いの領収書は送信されません。第 1 期が 0 の場合、この支払いは $0 の支払いです。以降の支払いは通常期間の金額を想定として記録します。顧客には代わりに「プラン変更」のメールが届き、新しいプランの割引前の通常価格、次回請求日、次回請求額（その期間に割引が適用される場合は割引後の金額）が表示されます。第 1 期の金額や割引の内訳は表示されません。支払い記録には第 1 期の各金額が残ります。以降の更新では上記のとおり領収書が送信されます。

​

金額、領収書、使用回数

• 割引は税込価格に適用されます。 パーセンテージ割引は通貨の最小単位に切り捨てます。固定額で合計がゼロを下回ることはなく、100% オフでは 0 円の注文になります。
• 注文、支払い記録、領収書、Dashboard には 3 つの金額が表示されます：元の価格、割引額、購入者の支払額。返金の上限は支払額です。
• 注文の価格スナップショットには表示価格が記録されます。 単発注文でもサブスクリプション注文でも、スナップショットの total は割引前の税込価格です。各請求の割引後の金額は支払い記録（snapshotAmountDetails.total）にあります。
• 割引のある領収書には、元の価格、割引、小計（割引後・税抜）、税額、支払額の順に表示されます。小計と税額の行は課税される場合のみ表示されます。
• 使用回数は支払い成功時に加算されます —— サブスクリプションでは割引される最初の請求です（サブスクリプションを参照）。注文がキャンセルまたは期限切れになると回数が戻り、購入者は再びコードを使えます。返金しても使用回数は戻りません。

​

次のステップ