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 までに設定すると、次のようになります。

クーポンを適用する

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

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

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

スクリプトクーポンは、項目のクーポンには使用できません。
スクリプトクーポンを他のスクリプトクーポンとスタックすることはできません。
スクリプトクーポンは、Quote (見積もり) オブジェクトでは使用できません。
スクリプトクーポンは、Customer オブジェクトでは使用できません。

スクリプトを作成する

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

メモ

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

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

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

Discount calculator interface
export type DiscountCalculationFunction<C> = (
  run_context: RunContext,
  configuration: C,
  discountable_item: DiscountableItem,
) => DiscountResult;

設定

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

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

DiscountableItem

DiscountableItem を割引計算ツールに渡して、このデータをスクリプト内で使用できるようにします。例として、割引可能な項目は次のようになります。パラメーターの最新の定義については、SDK を参照してください。スクリプトに渡される Customer などの使い慣れた Stripe オブジェクトを確認できます。ただし、これらのオブジェクトには、API で使用できるデータのサブセットのみが含まれます。

DiscountableItem definition
export interface DiscountableLineItem {
  subtotal: MonetaryAmount;
  quantity?: number | null;
  period: TimeRange;
  price?: Price | null;
}

export interface DiscountableItem {
  line_items: Array<DiscountableLineItem>;
  gross_amount: MonetaryAmount;
  customer?: Customer | null;
  billing_reason?: BillingReason | null;
  subscription?: Subscription | null;
}

DiscountResult

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

Discountable result
export interface DiscountResult {
  discount: Discount;
}

割引の結果を返す例:

Sample Discountable result (truncated)
return {
    discount: {
      amount: {
        amount: discountAmount,
        currency: item.gross_amount.currency,
      },
    },
  };

ベストプラクティス

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

サンプルスクリプト

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

上限額付きの割引率

Percent-up-to-max script  (truncated)
import type {
  ComputeDiscountsFunction,
  DiscountCalculation,
  DiscountableItem,
  DiscountResult,
} from '@stripe/scripts/discount_calculation';

import type {PositiveMonetaryAmount, Percent, RunContext} from '@stripe/scripts';

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

/**
 * Gives a percentage off discount up to a maximum discount amount
 *
 * @param {DiscountCalculatorConfiguration} config-The configuration containing max discount amount and discount percent
 * @param {DiscountableItem} item-The item to apply discounts to
 * @returns {DiscountResult} The discounts applied to the item
 */
const percentOffUptoMaxDiscount: ComputeDiscountsFunction<
  DiscountCalculatorConfiguration
> = (
  run_context: RunContext,
  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,
      },
    },
  };
};

const computePercentOffUptoMaxDiscount: DiscountCalculation<
  DiscountCalculatorConfiguration
> = {
  computeDiscounts: percentOffUptoMaxDiscount,
};

export default computePercentOffUptoMaxDiscount;

スクリプトをテストする

Stripe が作成するロジックをテストして、ワークフローに習熟することを推奨しています。プライベートプレビューにアクセスできる場合、Stripe が貴社の独自のロジックをサンドボックスまたはテスト環境アカウントに読み込みます。それにより貴社で必要なテストを実施して期待どおりに動作するかを確認できます。テスト環境での確認が終了したら、Stripe は貴社のスクリプトを貴社の本番環境アカウントにアップロードします。

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

スクリプトの作成、テスト、パッケージ化のためのツールを使用して、パブリック SDK にアクセスできます。パッケージ化されたスクリプトを Stripe に送信してレビューを受けることができます。

貴社の承認をいただいてから、Stripe が貴社の独自のロジックをご希望のサンドボックスまたはテスト環境にインポートします。それが期待通りに動作するかをご確認いただいた後、貴社の本番環境に適用します。

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

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

スクリプトクーポンを関連付けることができるのは、サブスクリプションか請求書のみです。
プレビュー期間中は、Connect の連結アカウントにスクリプトを配布することはできません。