subscription-billing

サブスクリプション請求

概要

サブスクリプション請求では、顧客が毎週、毎月、または毎年など、定期的なスケジュールで自動的に支払いを行います。Shopify、WooCommerce、BigCommerce には、それぞれ専用のサブスクリプションアプリとプラグインがあり、初回のチェックアウト、定期請求、決済失敗時の回収（督促）、プラン変更、一時停止、解約まで、ライフサイクル全体に対応します。ヘッドレスストアフロントでは、Stripe Subscriptions を API 経由で利用できるため、請求ロジックを一から構築する必要はありません。

このスキルを使用する場面

• サブスクリプションボックス、会員制サービス、または「定期購入で割引」プログラムを構築する場合
• 現在のサブスクリプションロジックが手動で、顧客数の増加に対応できていない場合
• 督促（決済失敗時の回収）が自動化されておらず、不必要な解約につながっている場合
• 顧客がプランのアップグレード、ダウングレード、一時停止、解約をセルフサービスで行う必要がある場合

基本的な手順

ステップ 1：利用するプラットフォームを特定し、適切なサブスクリプションツールを選ぶ

プラットフォーム	推奨ツール	備考
Shopify	Recharge または Seal Subscriptions または Bold Subscriptions（Shopify App Store）	Shopify にはネイティブの Subscriptions API があります。Recharge は最も広く利用されているサードパーティアプリで、Seal は比較的新しく、低価格の選択肢です
Shopify（シンプルな用途）	Shopify Subscriptions（組み込み、無料）	基本的なサブスクリプションに適しています。2024 年にリリースされ、シンプルな定期注文に対応します
WooCommerce	WooCommerce Subscriptions（年額 $199、公式 WooCommerce 拡張機能）	公式の、最も包括的な WooCommerce サブスクリプションソリューションです。請求、督促、管理のすべてに対応します
BigCommerce	Recurly（BigCommerce App Marketplace 経由）または Rebilly	BigCommerce にはネイティブのサブスクリプション機能がありません。サードパーティアプリが対応します
カスタム／ヘッドレス	Stripe Subscriptions	Stripe Subscriptions は、Webhook を使用して定期請求のライフサイクル全体に対応します

ステップ 2：プラットフォームでサブスクリプションを設定する

---

Shopify（Shopify Subscriptions — 組み込み、無料）

基本的なサブスクリプション商品の場合：

1. 設定 → アプリと販売チャネル → Shopify Subscriptions に移動します（App Store からインストールが必要な場合があります）
2. 商品 に移動し、サブスクリプション対象にする商品を開きます
3. 購入オプション の下にある サブスクリプションプランを追加 をクリックします
4. 次の項目を設定します：
   • 請求頻度：毎週、毎月、X か月ごと
   • 購読者向け割引（例：通常購入より 10％割引）
   • 無料トライアル期間（任意）
5. 商品ページに「通常購入」と「定期購入で割引」の両方のオプションが表示されます

Shopify Subscriptions は、定期請求、決済失敗時のメール、サブスクリプションを管理するための顧客ポータルに対応します。高度な督促、分析、購読者ポータルには、Recharge または Seal Subscriptions を使用してください。

Shopify（Recharge — 大規模運用におすすめ）

1. Shopify App Store から Recharge をインストールします
2. Recharge → Settings → Payment Processors で Shopify ストアと Stripe アカウントを接続します
3. Recharge → Products → Add product でサブスクリプション商品を設定します：
   • サブスクリプションとして購入できる Shopify 商品を選択します
   • 請求間隔（毎週、毎月、2 か月ごとなど）を設定します
   • 購読者向け割引を設定します
4. 顧客ポータルを設定します。Recharge → Customer Portal に移動し、購読者が自分で管理できる項目（一時停止、スキップ、日付変更、解約、商品変更）を設定します
5. 督促を設定します。Recharge → Settings → Dunning に移動し、決済失敗時の再試行スケジュールとメールシーケンスを設定します

Recharge の督促のデフォルト設定：

• 0 日目：初回の決済失敗 → 顧客にメールを送信
• 3 日目：決済を再試行 → 顧客にメールを送信
• 7 日目：決済を再試行 → 最終警告メールを送信
• 14 日目：決済を再試行 → それでも失敗している場合はサブスクリプションを解約

WooCommerce（WooCommerce Subscriptions）

1. woocommerce.com/products/woocommerce-subscriptions から WooCommerce Subscriptions を購入してインストールします
2. サブスクリプション商品を作成します。Products → Add New に移動し、商品タイプを Simple subscription または Variable subscription に設定します
3. Subscription data で設定します：
   • 請求期間：毎日、毎週、毎月、毎年
   • 請求間隔：1、2、3... 期間ごと
   • サブスクリプション期間：継続または期間限定（例：12 か月）
   • 登録料（任意）
   • 無料トライアル期間（任意）
   • サブスクライバー割引（通常価格とセール価格の比較で設定）
4. 決済方法を設定します。WooCommerce → Settings → Payments に移動し、決済ゲートウェイが継続課金に対応していることを確認します（WooCommerce Stripe プラグイン経由の Stripe、WooCommerce PayPal Payments 経由の PayPal）
5. ダニングを設定します。WooCommerce → Settings → Subscriptions → Failing payments に移動し、再試行ルールとメールテンプレートを設定します

WooCommerce のカスタマーポータル： お客様は My Account → Subscriptions ページからサブスクリプションを管理できます。WooCommerce Subscriptions には、一時停止、キャンセル、決済方法の更新機能がデフォルトで用意されています。

BigCommerce（Recurly）

1. recurly.com で登録し、料金を設定したプラン（月額、年額など）を作成します
2. BigCommerce App Marketplace から Recurly アプリをインストールし、ストアに接続します
3. Recurly のプランに紐付けたサブスクリプション商品を作成します
4. Recurly は、チェックアウト、継続課金、ダニング、請求書発行、サブスクライバーポータルを処理します
5. Recurly → Configuration → Dunning Campaigns でダニングを設定します。再試行スケジュールとメールの内容を設定します

---

カスタム／ヘッドレス

継続課金のライフサイクル全体には Stripe Subscriptions を使用します。

サブスクリプションプランを作成する： Stripe Dashboard → Products で、継続課金の価格が設定された商品（例：「月額プラン — $29/月」）を作成します。Price ID（price_ で始まります）をコピーします。

顧客をサブスクライブする：

// Create or retrieve the Stripe customer
const customer = await stripe.customers.create({
  email: customerEmail,
  payment_method: paymentMethodId,
  invoice_settings: { default_payment_method: paymentMethodId },
});

// Create the subscription
const subscription = await stripe.subscriptions.create({
  customer: customer.id,
  items: [{ price: 'price_monthly_pro_29' }], // Price ID from Stripe Dashboard
  payment_behavior: 'default_incomplete', // Create subscription, then confirm payment
  payment_settings: { save_default_payment_method: 'on_subscription' },
  expand: ['latest_invoice.payment_intent'],
  trial_period_days: 14, // Optional trial
  metadata: { customer_id: customerId },
});

// Return client_secret for 3DS confirmation if needed
const clientSecret = subscription.latest_invoice?.payment_intent?.client_secret;
res.json({ subscriptionId: subscription.id, clientSecret });

Webhook 経由でサブスクリプションのステータスを同期する：

// Webhook handler for subscription events
async function handleSubscriptionWebhook(event) {
  switch (event.type) {
    case 'customer.subscription.updated':
      await syncSubscriptionStatus(event.data.object);
      break;

    case 'customer.subscription.deleted':
      // Subscription cancelled — revoke access
      await db.subscriptions.update({
        where: { stripeSubscriptionId: event.data.object.id },
        data: { status: 'cancelled', cancelledAt: new Date() },
      });
      break;

    case 'invoice.payment_succeeded':
      await recordSuccessfulBillingCycle(event.data.object);
      break;

    case 'invoice.payment_failed':
      // Send dunning email — Stripe retries automatically per your settings
      await sendDunningEmail(event.data.object);
      break;

    case 'customer.subscription.trial_will_end':
      // Send trial ending email 3 days before trial ends
      await sendTrialEndingEmail(event.data.object);
      break;
  }
}

Stripe Dashboard でダニングを設定する： Stripe Dashboard → Billing → Settings → Smart Retries に移動します。Smart Retries を有効にします。Stripe の機械学習ベースの再試行タイミングは、固定スケジュールよりも優れた成果を発揮します。また、すべての再試行が失敗した後にサブスクリプションを自動キャンセルするよう、Stripe Dashboard → Billing → Settings → Automatic collection で設定します。

日割り計算によるプラン変更：

// Upgrade or downgrade a subscription
const subscription = await stripe.subscriptions.retrieve(stripeSubscriptionId);

await stripe.subscriptions.update(stripeSubscriptionId, {
  items: [{ id: subscription.items.data[0].id, price: newPriceId }],
  proration_behavior: 'create_prorations', // Charge/credit the difference immediately
});
// Stripe creates a prorated invoice automatically

期間終了時のアクセスを維持したままキャンセルする：

// Cancel at period end — customer retains access until the next billing date
await stripe.subscriptions.update(stripeSubscriptionId, {
  cancel_at_period_end: true,
});

// Immediate cancellation
await stripe.subscriptions.cancel(stripeSubscriptionId);

ベストプラクティス

• プラットフォーム標準のサブスクリプションツールを使用する — WooCommerce Subscriptions、Shopify の Recharge、Stripe Subscriptions は、いずれも本番環境で十分に検証されており、支払い失敗、日割り計算、税率変更などの例外ケースを適切に処理します
• サブスクリプションの状態を Stripe のみに保存しない — Webhook 経由でサブスクリプションのステータスを必ずデータベースに同期します。ステータスを確認するためにページを読み込むたびに Stripe を呼び出さないでください
• Stripe で Smart Retries を設定する — Stripe Dashboard → Billing → Settings で有効にします。機械学習ベースの再試行タイミングを使うと、固定スケジュールよりも多くの支払い失敗を回収できます
• 再試行のたびにダニングメールを送信する — 「支払いに失敗しました」→「アカウントが危険な状態です」→「アクセスが停止されます」のように緊急度を段階的に高め、決済方法を更新するための直接リンクを含めます
• お客様自身で手続きできるようにする — プラン変更、一時停止、キャンセル用のカスタマーポータルを構築するか、Stripe Dashboard → Billing → Customer portal にある Stripe のホスト型カスタマーポータルを使用します。これによりサポートの負荷を軽減できます
• アップグレードは直ちに日割り計算し、ダウングレードは期間終了時に適用する — アップグレードでは差額を今すぐ請求し、ダウングレードは複雑な一部返金を避けるため、次回の更新時に適用します

よくある落とし穴

問題	解決策
解約後もサブスクリプションが有効と表示される	Webhook 経由でステータスを同期します。customer.subscription.deleted でデータベースを更新する必要があります。ページの読み込み時に Stripe にステータスを問い合わせる方法は使用しないでください
WooCommerce Subscriptions で失敗した支払いが再試行されない	決済ゲートウェイがトークン化された継続課金に対応しているか確認します。WooCommerce Stripe プラグイン経由の Stripe は対応していますが、基本的な PayPal Standard は対応していません
顧客が知らないうちにトライアルが有料プランに切り替わる	3 日前に trial_will_end メールを送信します（Stripe は Webhook を自動的に送信します。Recharge と WooCommerce Subscriptions ではデフォルトでこの処理が行われます）
Webhook の再試行時に督促メールが重複して送信される	次のメールを送信する前に、請求書の試行回数が最後に送信した督促メールと一致することを確認します。請求書 ID と試行回数を冪等性キーとして使用します
プランのアップグレード時に按分請求が予期せず発生する	プラン変更を適用する前に、次回の請求書のプレビューを表示します（Stripe の場合は stripe.invoices.retrieveUpcoming() を使用します）。まず顧客に按分額を表示します

関連スキル

• @stripe-integration
• @order-processing-pipeline
• @tax-calculation
• @invoice-generation-automation