Stripe Billing にカスタムの割引ロジックを実装する非公開プレビュー

サブスクリプションと請求書の割引額を計算するカスタムロジックを実装します。

Stripe Billing では、カスタムロジックを使用してクーポンを設定し、サブスクリプションと請求書の割引額を、一定割合や一定額以外の方法で算出することができます。以下は、1 つのクーポンでできることの例です。

年額登録者には 10% オフを提供、月額登録者には割引なし。
20% オフの提供 (最大 1000 USD)。高価値の顧客 (メタデータでタグ付けされた顧客) にのみ割引を提供。
段階割引を提供 (10 シート以上購入した場合に 100 USD オフ、それ以外の場合は 30 USD オフ、など)。

始める

カスタムロジックが請求ワークフローとどのように連携されるかを理解するには、Stripe のスクリプト SDK で Billing ユーザーが使用できる Stripe 作成のスクリプトをご覧ください。

これらのスクリプトは、スクリプト言語を使用して固有のロジックを構築するための基盤として使用できます。サンドボックスで始めることをお勧めします。

Stripe が作成したカスタムロジックを使用する

Stripe が作成 したカスタムロジックを使用してクーポンを作成するには、クーポンの作成 ページに移動して、最大割引率 タイプを選択します。これにより、独自のスクリプトを作成する前に、カスタムロジックスクリプトがクーポンにどのように適用されるかがわかります。

クーポンを作成する

このプロセスはサンドボックスで開始することをお勧めします。テスト環境のスクリプトはサポートされていません。テストでは、サンドボックス環境を使用する必要があります。

ノーコードでクーポンを作成

Stripe が作成したカスタムロジックでクーポンを作成するには、クーポンの作成ページに移動し、クーポンタイプ Percentage off up to maximum (Stripe が作成したスクリプトを使用) を使用します。

API を使用してクーポンを作成する

API を使用してスクリプトクーポンを作成する場合は、スクリプトの仕様について以下の表を参照してください。

商品名	ID	スクリプト定義
最大割引率	`bfsimpl_61S9T2y7zlKu9YlG116S8pZoN2SQpuwOX348dhXM0R9c`	スクリプト定義を参照
Configuration fields `{ max_discount_amount: { amount: number; currency: string; }, discount_percent: number; }` `max_discount_amount.amount`: value in the currency’s minor unit `max_discount_amount.currency`: The three-letter ISO code for the currency `discount_percent`: value as percentage

たとえば、Percentage off up to maximum を使用して、20% オフのクーポンの上限を 100 USD までに設定すると、次のようになります。

クーポンを適用する

クーポンを作成したら、通常のクーポンと同ジプロセスに従い、サブスクリプションや請求書に適用します。詳しい手順については、クーポンをご覧ください。

スクリプトクーポンの制限事項

スクリプトクーポンには、次の制限があります。

スクリプトクーポンは、項目のクーポンには使用できません。
スクリプトクーポンを他のクーポンと重ねて表示することはできません。
You can’t use script coupons on Quote objects.
スクリプトクーポンは、Checkout Sessions の payment モードではサポートされていません。
スクリプトクーポンは、2025-03-31.preview 以降の API バージョンでのみサポートされます。

スクリプトを作成する

特定のビジネスニーズを満たすために、スクリプト言語を使用して独自のカスタムロジックを作成できます。

注

お客様は、スクリプトに目的の機能が反映されていることを確認する責任を負います。専有の機密情報 (PII など) や悪意のあるコードを入力しないようにしてください。

割引計算機のインターフェース

すべての coupon スクリプトは、Stripe が定義する割引計算ツールのインターフェイスに従う必要があります。

Discount calculator interface
export type DiscountFunction<T> = (
  configuration: T,
  discountableItem: DiscountableItem,
) => DiscountResult;

設定

ユーザーがスクリプトタイプのクーポンを作成するときに指定する必要がある構成値を定義できます。クーポンに設定された構成値は、呼び出すたびに割引関数に渡されます。

Sample script configuration
export type DiscountCalculatorConfiguration = {
  max_discount_amount: {
    amount: number;
    currency: string;
  },
  discount_percent: number;
};

DiscountableItem

DiscountableItem を割引計算ツールに渡し、このデータをスクリプト内で使用可能にしています。スクリプトには、次の情報が提供されています。

DiscountableItem definition
export interface DiscountableItem {
  id: string;
  gross_amount: MonetaryAmount;
  line_items: Array<DiscountableLineItem>;
}
export interface DiscountableLineItem {
  id: string;
  subtotal: MonetaryAmount;
  price_id?: string;
  is_free_trial: boolean;
  is_recurring: boolean;
  quantity?: number;
  unit_amount?: MonetaryAmount;
  period?: TimeRange;
}

DiscountResult

スクリプトは割引の結果を返す必要があります。

Discountable result
export type DiscountStatus = 'APPLIED' | 'NOT_APPLIED';

export type Discount = {
 amount: MonetaryAmount;
 status: DiscountStatus;
 reason?: string;
};

export type ItemDiscount = {
 discountable_item_id: string;
 discount: Discount;
};

export type DiscountResult = {
 discount?: Discount;
 line_item_discounts: Array<ItemDiscount>;
};

注

line_item_discounts は請求書の項目に適用される割引で、最上位の discount にはロールアップされません。最上位の discount は、line_item_discount とは無関係に請求書に適用される割引です。

割引の結果を返す例:

Sample Discountable result (truncated)
return {
  discount: {
    amount: {
      amount: discount_amount,
      currency: item.gross_amount.currency,
    },
    status: discount_amount > 0 ? 'APPLIED' : 'NOT_APPLIED',
    reason: discount_amount > 0 ? 'Discount applied' : 'No discount applied',
  },
  line_item_discounts: [],
};

ベストプラクティス

可能な場合は、設定に Stripe が定義したタイプを使用します (例: MonetaryAmount)
割引を適用する前に、通貨チェックを実行してください。

サンプルスクリプト

プライベートプレビュー版にアクセスできる場合は、カスタムの割引ロジックを Stripe Billing チームにメールで送信できます。以下のサンプルスクリプトを使用すると、作成できるカスタムロジックのニュアンスを掴めるほか、作業開始時に必要なテンプレートを確認できます。

上限額付きの割引率

Percent-up-to-max script  (truncated)
import {MonetaryAmount, Percent} from '@stripe/scripts';
import {
  DiscountCalculatorFunction,
  DiscountableItem,
  DiscountResult,
} from '@stripe/scripts/discounts';

/**
 * Configuration for the discount calculator function
 */
export type DiscountCalculatorConfiguration = {
  max_discount_amount: MonetaryAmount;
  discount_percent: Percent;
};

/**
 * Gives a percentage off discount upto a maximum discount amount
 *
 * @param {DiscountCalculatorConfiguration} config - The configuration containing max discount amount and discount percent
 * @param {DiscountableItem} item - The items to apply discounts to
 * @returns {DiscountResult} - The discounts applied to the items
 */
const percentOffUptoMaxDiscount: DiscountCalculatorFunction<
  DiscountCalculatorConfiguration
> = (
  config: DiscountCalculatorConfiguration,
  item: DiscountableItem,
): DiscountResult => {
  const {max_discount_amount, discount_percent} = config;
  let discountAmount = 0;

  if (
    item.gross_amount.currency.toLowerCase().trim() ===
    max_discount_amount.currency.toLowerCase().trim()
  ) {
    const discountAmountValue =
      (item.gross_amount.amount * discount_percent) / 100;
    discountAmount = Math.min(discountAmountValue, max_discount_amount.amount);
  }

  return {
    discount: {
      amount: {
        amount: discountAmount,
        currency: item.gross_amount.currency,
      },
      status: discountAmount > 0 ? 'APPLIED' : 'NOT_APPLIED',
      reason: discountAmount > 0 ? 'Discount applied' : 'No discount applied',
    },
    line_item_discounts: [],
  };
};

export default percentOffUptoMaxDiscount;

スクリプトをテストする

Stripe が作成したロジックをテストして、ワークフローに慣れることをお勧めします。プライベートプレビュー版にアクセスできる場合は、カスタムロジックがアカウントのサンドボックスに読み込まれます。そこで必要なテストを実行してロジックが想定どおりに動作することを確認できます。サンドボックス環境でロジックを検証すると、Stripe はスクリプトを本番アカウントにアップロードします。

レビューとテスト用のスクリプトを送信する

プライベートプレビュー版に承認されると、スクリプトの作成、テスト、パッケージ化のためのツールを含む SDK にアクセスできるようになります。パッケージ化されたスクリプトを Stripe に送信してレビューを受けることができます。

承認されると、カスタムロジックを選択したサンドボックスにインポートされテストされますので、それから本番環境に適用します。

非公開ベータの適格性基準

この機能はプライベートプレビュー版であり、まだ開発中です。スクリプトの開発が進む中で、機能が変更される可能性があります。次の考慮事項に注意してください。

バージョン 2025-03-31.preview 以降を使用する必要があります。新規ユーザーの場合はこれがデフォルトのバージョンですが、既存ユーザーの場合はアップグレードできます。
スクリプトクーポンを関連付けることができるのは、新しいサブスクリプションか請求書のみです。
Checkout は、subscription モードではスクリプト対応のプロモーションコードの使用のみをサポートしています。
プレビュー期間中は、Connect の連結アカウントにスクリプトを配布することはできません。