# カスタムクーポン サブスクリプションと請求書の割引額を計算するカスタムロジックを実装します。 Stripe Billing では、カスタムロジックを使用してクーポンを設定し、サブスクリプションと請求書の割引額を、一定割合や一定額以外の方法で算出することができます。以下は、1 つのクーポンでできることの例です。 - 年額登録者には 10% オフを提供、月額登録者には割引なし。 - 20% オフの提供 (最大 1000 USD)。高価値の顧客 (メタデータでタグ付けされた顧客) にのみ割引を提供。 - 段階割引を提供 (10 シート以上購入した場合に 100 USD オフ、それ以外の場合は 30 USD オフ、など)。 ## 始める カスタムロジックが請求ワークフローとどのように連携されるかを理解するには、Stripe の[スクリプト SDK](https://github.com/stripe/scripts) で Billing ユーザーが使用できる Stripe 作成のスクリプトをご覧ください。 これらのスクリプトは、弊社の[スクリプト言語](https://docs.stripe.com/billing/scripts/script-language.md)を使用して独自のロジックを構築する際の基盤として使用できます。まずは[サンドボックス](https://docs.stripe.com/sandboxes.md)で開始することをお勧めします。 ## Stripe が作成したカスタムロジックを使用する **Stripe が作成** したカスタムロジックを使用してクーポンを作成するには、**クーポンの作成** ページに移動して、**最大割引率** タイプを選択します。これにより、独自のスクリプトを作成する前に、カスタムロジックスクリプトがクーポンにどのように適用されるかがわかります。 ### クーポンを作成する このプロセスは、[サンドボックス](https://docs.stripe.com/sandboxes.md)で開始することをお勧めします。 #### ノーコードでクーポンを作成 Stripe が作成したカスタムロジックでクーポンを作成するには、[クーポンの作成ページ](https://dashboard.stripe.com/test/coupons/create)に移動し、クーポンタイプ `Percentage off up to maximum` (Stripe が作成したスクリプトを使用) を使用します。 #### API を使用してクーポンを作成する API を使用してスクリプトクーポンを作成する場合は、スクリプトの仕様について以下の表を参照してください。 | 商品名 | ID | スクリプト定義 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 最大割引率 | `bfsimpl_61S9T2y7zlKu9YlG116S8pZoN2SQpuwOX348dhXM0R9c` | [スクリプト定義を参照 :external: link-to-percent-off-up-to-maximum-script](https://docs.stripe.com/billing/subscriptions/script-coupons.md#percentage-off-up-to-maximum-example) | | ```js { max_discount_amount: { amount: number; currency: string; }, discount_percent: number; } ``` - `max_discount_amount.amount`: value in the [currency’s minor unit](https://docs.stripe.com/currencies.md#minor-units) - `max_discount_amount.currency`: The three-letter [ISO code for the currency](https://docs.stripe.com/currencies.md#presentment-currencies) - `discount_percent`: value as percentage | たとえば、`Percentage off up to maximum` を使用して、20% オフのクーポンの上限を 100 USD までに設定すると、次のようになります。 ```curl curl https://api.stripe.com/v1/coupons \ -u "<>:" \ -d duration=forever \ -d "name=My coupon" \ -d "script[id]=bfsimpl_61S9T2y7zlKu9YlG116S8pZoN2SQpuwOX348dhXM0R9c" \ -d "script[configuration][max_discount_amount][amount]=10000" \ -d "script[configuration][max_discount_amount][currency]=usd" \ -d "script[configuration][discount_percent]=20" ``` ### クーポンを適用する クーポンを作成したら、通常のクーポンと同ジプロセスに従い、サブスクリプションや請求書に適用します。詳しい手順については、[クーポン](https://docs.stripe.com/billing/subscriptions/coupons.md)をご覧ください。 ### スクリプトクーポンの制限事項 スクリプトクーポンには、次の制限があります。 - スクリプトクーポンは、項目のクーポンには使用できません。 - スクリプトクーポンを他のスクリプトクーポンとスタックすることはできません。 - スクリプトクーポンは、[Quote (見積もり)](https://docs.stripe.com/api/quotes.md) オブジェクトでは使用できません。 - スクリプトクーポンは、[Customer](https://docs.stripe.com/api/customer.md) オブジェクトでは使用できません。 ## スクリプトを作成する 特定のビジネスニーズを満たすために、[スクリプト言語](https://docs.stripe.com/billing/scripts/script-language.md)を使用して独自のカスタムロジックを作成できます。 > #### スクリプトを確認する > > スクリプトに意図した機能が反映されていることを確認する責任はお客様にあります。機密情報や秘密情報 (たとえば、*PII* (Personally identifiable information (PII) is information that, when used alone or with other relevant data, can identify an individual. Examples include passport numbers, driver's license, mailing address, or credit card information))、または悪意のあるコードは入力しないでください。 ### 割引計算機のインターフェース すべての coupon スクリプトは、Stripe が定義する割引計算ツールのインターフェイスに従う必要があります。 ```typescript export type DiscountCalculationFunction = ( run_context: RunContext, configuration: C, discountable_item: DiscountableItem, ) => DiscountResult; ``` #### 設定 ユーザーがスクリプトタイプのクーポンを作成するときに指定する必要がある構成値を定義できます。クーポンに設定された構成値は、呼び出すたびに割引関数に渡されます。 ```typescript export type DiscountCalculatorConfiguration = { max_discount_amount: { amount: number; currency: string; }, discount_percent: number; }; ``` #### DiscountableItem `DiscountableItem` を割引計算ツールに渡して、このデータをスクリプト内で使用できるようにします。例として、割引可能な項目は次のようになります。パラメーターの最新の定義については、[SDK](https://github.com/stripe/scripts/blob/main/src/discount_calculation/types.ts) を参照してください。スクリプトに渡される [Customer](https://docs.stripe.com/api/customer/object.md) などの使い慣れた Stripe オブジェクトを確認できます。ただし、これらのオブジェクトには、API で使用できるデータのサブセットのみが含まれます。 ```typescript export interface DiscountableLineItem { subtotal: MonetaryAmount; quantity?: number | null; period: TimeRange; price?: Price | null; } export interface DiscountableItem { line_items: Array; gross_amount: MonetaryAmount; customer?: Customer | null; billing_reason?: BillingReason | null; subscription?: Subscription | null; } ``` #### DiscountResult スクリプトは割引の結果を返す必要があります。 ```typescript export interface DiscountResult { discount: Discount; } ``` 割引の結果を返す例: ```typescript return { discount: { amount: { amount: discountAmount, currency: item.gross_amount.currency, }, }, }; ``` ## サンプルスクリプト プライベートプレビュー版にアクセスできる場合は、カスタムの割引ロジックを Stripe Billing チームにメールで送信できます。以下のサンプルスクリプトを使用すると、作成できるカスタムロジックのニュアンスを掴めるほか、作業開始時に必要なテンプレートを確認できます。 ### 上限額付きの割引率 ```typescript 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](https://github.com/stripe/scripts) にアクセスできます。パッケージ化されたスクリプトを Stripe に送信してレビューを受けることができます。 貴社の承認をいただいてから、Stripe が貴社の独自のロジックをご希望のサンドボックスまたはテスト環境にインポートします。それが期待通りに動作するかをご確認いただいた後、貴社の本番環境に適用します。 ## データ検証要件 スクリプトを正常に実行するには、これらの要件を満たす必要があります。違反すると検証エラーが発生します。 - 呼び出しのたびに、`discount.amount` に `amount` (数値) と `currency` (文字列) の両方を含む `DiscountResult` を返す必要があります。 - `amount` は 0 以上である必要があります。 - `currency` は請求書の通貨と一致する必要があります。 ## ベストプラクティス - 割引を計算する前に、通貨を確認します。通貨が一致しない場合は、割引額 0 を返します。 - 組み込みの検証を利用するには、設定で `PositiveMonetaryAmount` や `Percent` などの Stripe 提供の SDK 型を使用します。 - 複数の項目を含む請求書をテストして、割引が総額に対して正しく適用されることを確認します。