「明日から有効」なクーポンをStripeで簡単に作る方法

飲食店やリテールアプリの開発でよくある要件に、「ご来店ありがとうございます。これは明日から使える割引チケットです」というシナリオがあります。これを Stripe で実装しようとした時、Coupon APIだけを調べると「開始日 (start_date) が見当たらない」という問題に遭遇します。

この記事では、Stripe APIを使って特定のタイミングから利用できるようになるクーポンを作る方法を紹介します。

Promotion Code APIでクーポンを発行する

開始日や対象商品などの制限をかけたい場合、クーポン (Coupon) ではなく、プロモーションコード (Promotion Code) APIを利用しましょう。

Promotion Code API には starts_at パラメータが用意されています。この値を利用することで、下のコードのように特定の日付から利用できるクーポンコードを発行できます。

// 明日の0時0分0秒を取得
const validFrom = new Date();
validFrom.setDate(validFrom.getDate() + 1);
validFrom.setHours(0, 0, 0, 0);

// Unix Timestamp (秒) に変換
const startsAtTimestamp = Math.floor(validFrom.getTime() / 1000);

// 顧客専用のプロモーションコードを作成
const promoCode = await stripe.promotionCodes.create({
  promotion: {
    type: 'coupon',
    coupon: coupon.id,          // ベースとなるクーポンの ID
  },
  code: `THANKS-${Date.now()}`, // 顧客に入力させるコード (ユニークである必要あり)
  starts_at: startsAtTimestamp, // ★ここで開始日時を指定
  
  // オプション: 特定の顧客 ID に紐付ける場合
  // customer: 'cus_xxxxxxxx',
});

console.log(`明日から使えるコード: ${promoCode.code}`);

CouponとPromotion Code

自分もよく混同するのですが、Stripeでの割引は２つのモデルにて構成されています。Coupon は「10%オフ」「500円引き」といった割引の内容を定義します。そしてPromotion Code は顧客が入力するコード（例: SALE2025）で、顧客が入力する or システムが顧客に設定する割引の条件を定義します。

ざっくりまとめると、「割引内容はCouponで定義」「割引の利用条件はPromotion Codeで定義」のような構成です。そのため、今回のような利用開始日を設定するためには、Promotion Code APIを利用する必要があります。

まとめ

Coupon API には開始日設定がありません。そのため割引を利用できる開始日を設定したい場合は、Promotion Code API の starts_at を使う必要があります。

Stripeは柔軟かつスケーラブルな利用を実現させるため、CouponとPromotion Codeのように抽象化・階層化されたAPI構造になっていることが多いです。そのため、１つのAPIだけではなく、総合的にドキュメントをチェックする必要があることに注意が必要です。