混合期間のサブスクリプション非公開プレビュー

期間が混在するサブスクリプションを使用すると、1 つのサブスクリプションで異なる複数の継続価格を請求できます。これにより、1 つのサブスクリプション内で異なる料金体系を組み合わせることができます。

たとえば、500 USD の年額の定額料金と月額の使用量ベースの料金が指定されたサービスに登録している顧客の場合、両方の料金を同じサブスクリプションの項目として含めることができます。Stripe は、項目レベルの請求サイクルが一致する場合はまとめて請求書を作成し、1 つの項目のみが期限を迎える場合は個別の請求書を作成します。

期間が混在するサブスクリプションの利用を始める

期間が混在するサブスクリプションを有効にするには、次の API エンドポイントで billing_mode=flexible を設定し、API バージョンを 2025-04-30.preview 以降にアップグレードする必要があります。

• サブスクリプションを作成する
• 請求書のプレビューを作成する
• Checkout Session を作成する

期間が混在するサブスクリプションを作成する

異なる継続期間値を持つ価格を使用してサブスクリプションを作成し、ばらばらのタイミングで更新されるサブスクリプションアイテムに対して請求します。

四半期あたり 100 USD のサブスクリプションと月額 15 USD のサブスクリプションを 2024 年 1 月 1 日付けで開始する場合、以下のようなサブスクリプションが作成されます。

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "items[0][price_data][currency]"=usd \
  -d "items[0][price_data][product]"=
{{PRODUCT_ID}} \
  -d "items[0][price_data][recurring][interval]"=month \
  -d "items[0][price_data][recurring][interval_count]"=1 \
  -d "items[0][price_data][unit_amount]"=1500 \
  -d "items[0][quantity]"=1 \
  -d "items[1][price_data][currency]"=usd \
  -d "items[1][price_data][product]"=
{{PRODUCT_ID}} \
  -d "items[1][price_data][recurring][interval]"=month \
  -d "items[1][price_data][recurring][interval_count]"=3 \
  -d "items[1][price_data][unit_amount]"=10000 \
  -d "items[1][quantity]"=1 \
  -d collection_method=send_invoice \
  -d days_until_due=5 \
  -d proration_behavior=none \
  -d billing_mode=flexible \
  -d "expand[0]"=latest_invoice

応答には、最初のインボイス (latest_invoice) に両方のアイテムと請求書を含むサブスクリプションが含まれます。

{
  "object": "subscription",
  "id": 
'{{SUBSCRIPTION_ID}}',
  "current_period_start": 1704067200, // Jan 1 2024
  "current_period_end": 1706745600, // Feb 1 2024
  "items": {
    "data": [
      {
        "id": "si_A",
        "price": "price_id_monthly",

2 月 1 日と 3 月 1 日に、サブスクリプションが更新され、月額料金の新しいインボイスが生成される。 4 月 1 日に、サブスクリプションの更新で月次と四半期の両方の料金のインボイスが作成されます。

サブスクリプションをキャンセルする

• 期間が混在するサブスクリプションまたはスケジュールをキャンセルすると、Stripe は、期間に関係なく、すべてのサブスクリプションアイテムをキャンセルします。
• サブスクリプションでは、請求書がサブスクリプション項目の 1 つに対してのみ請求される場合でも、督促の動作は 1 つです。支払いの再試行がすべて失敗した場合、Stripe はサブスクリプション全体をキャンセルし、構成されている督促の設定に従って、未払いまたは期日超過としてマークします。

混合期間のサブスクリプションの請求期間

各サブスクリプションアイテムには、独自のcurrent_period_start と current_period_end があります。

Stripe はサブスクリプションアイテムの請求期間に基づいて、サブスクリプションの現在の期間を設定します。

• current_period_start は、アイテムの current_period_start の日付の最大値 (最も遅い日付) です。
• current_period_end は、アイテムの current_period_end の日付の最小値 (最も早い日付) です。

subscription.current_period_end は、常にアイテムの現在のサイクルが終了する次の日付を示します。

たとえば、月次、隔月、四半期ごとのアイテムを含むサブスクリプションを 1 月 1 日に作成した場合、次の期間が含まれます。

2 月 1 日 (subscription.current_period_end) の更新後、サブスクリプションの現在の期間は、すべてのアイテムの最も遅い current_period_start と最も早い current_period_end に合わせて調整されます。

3 回目のサイクル後:

請求期間の調整

無料トライアル

アイテムレベルの請求期間の日付は、通常のサブスクリプションと同様に、無料トライアルの終了日の影響を受けます。サブスクリプションに将来の日付の trial_end が設定されている場合、すべての current_period_end の日付 (サブスクリプションとアイテム) も trial_end の日付に設定されます。

トライアル期間の終了時に一時停止して再開する

混合期間のサブスクリプションは、通常のサブスクリプションと同様に trial_settings.end_behavior.missing_payment_method パラメーターで決済手段を指定しないことで、トライアル終了時に一時停止するように設定できます。一時停止されたサブスクリプションは、通常のサブスクリプションと同様に stripe.subscription.resume を使用して再開することができます。proration_behavior: none パラメーターと billing_cycle_anchor パラメーターは、混合期間のサブスクリプションでのみサポートされます。

月次項目と隔月項目の混合間隔のサブスクリプションの場合

• billing_cycle_anchor = 1 月 1 日
• trial_end = 2 月 1 日
• trial_settings.end_behavior.missing_payment_method = 「一時停止」

この例では、決済手段が指定されていないことを理由にこのサブスクリプションが 2 月 1 日に一時停止され、2 月 15 日に proration_behavior: none で再開されるケースを想定しています。

期間が混在する場合の考慮事項

混合期間のサブスクリプションには、いくつかの制限があります。

サイクルの一致

すべてのサブスクリプション項目の価格サイクルは、サブスクリプションに設定されている最短の価格サイクルの倍数でなければなりません。価格サイクルの期間は、price.recurring.interval フィールドと price.recurring.interval_count フィールドを組み合わせて算出されます。

• サポートされている期間の組み合わせの例:

  • 1 カ月、3 カ月
  • 1 カ月、1 年
  • 1 日、1 週間
  • 1 日、3 カ月
  • 1 日、2 年
  • 2 週間、4 週間
  • 2 カ月、4 カ月、6 カ月

• サポートされていない期間の組み合わせの例:

  • 2 カ月、3 カ月
  • 4 カ月、6 カ月
  • 1 週間、1 カ月
  • 2 日、1 週間
  • 5 カ月、1 年

制限事項

プライベートプレビュー版の場合、期間が混在するサブスクリプションには、開発中に変更される可能性がある次の制限が適用されます。

• すべてのサブスクリプション項目の料金は、recurring.usage_type: licensed および billing_scheme: per_unit を指定する必要があります。従量制料金には対応していません。
• 期間が混在するサブスクリプションは、現在 Stripe API でのみ利用でき、カスタマーポータルでは利用できません。
• 期間が混在するサブスクリプションでは、キャンセル日の決定に使用するサブスクリプション項目の current_period_end が不明確であるため、cancel_at_period_end を使用することはできません。