スクリプトを使用してビジネスロジックを Stripe 上で直接プログラミングする非公開プレビュー

TypeScript を使用してカスタムロジックを作成し、Stripe の機能を拡張します。

Using a subset of Typescript, you can write and submit custom logic in Stripe. With scripts, you can:

特定の Stripe オブジェクトに対して独自のロジックを定義する
特定のビジネスニーズに合わせて Stripe アカウントをカスタマイズする
Stripe を標準機能を超えて拡張する

たとえば、スクリプトを使用して新しいクーポンにカスタム割引ロジックを作成して、そのクーポンをサブスクリプションと請求書に適用できます。

スクリプトのライフサイクル

スクリプトの使用方法については、次のスクリプトのライフサイクルを参照してください。

まず、サポートされているユースケースのカスタムロジックを作成します。
スクリプト作成の一環として、構成値を定義できます。これらは、スクリプトユーザがカスタムオブジェクトの作成時に渡すパラメータです。
レビューのためにスクリプトを送信した後、Stripe はそのスクリプトをスクリプトサービスに登録します。
その後、Coupon オブジェクトや Subscription オブジェクトなどのオブジェクトを作成するときにスクリプトを呼び出すことができます。

関数の引数

関数の引数は、次の 2 つのカテゴリーに分類できます。

作成者が定義した値

You can think of author-defined values having two audiences:

Script author: The script author defines the function (that is, the actual logic) and the input values to the function. For example, you could write a “percent-up-to-a-maximum” script where the author defines two input values (percent and maximum).
Script user: After the script authore defines the values, the script user can define the values for the two inputs through the Dashboard or API (for example, 10% off a 100 USD maximum).

スクリプト作成者は、スクリプトのどの部分をスクリプトユーザー向けにカスタマイズ可能にするかを決定します。その後、スクリプトユーザーは、スクリプトのカスタマイズ可能な部分に独自の値を適用します。

script configuration-1
export type scriptConfiguration = {
  max_discount_amount: {
    amount: number;
    currency: string;
  },
  discount_percent: number;
};

The SDK provides built-in types that you can use as part of your configuration definition. These built-in types render with a relevant input field UI in the Dashboard. If you have suggestions for new built-in types, contact scripts-preview@stripe.com or our Support team.

script configuration-2
import type {PositiveMonetaryAmount, Percent} from '@stripe/scripts';

export type scriptConfiguration = {
  max_discount_amount: PositiveMonetaryAmount;
  discount_percent: Percent;
};

Configuration values have default schema validations when the script user tries to set the values. In addition, you can define custom validation by referencing the schema validations. If we don’t support your validation use case, we recommend building the validation check into your function definition and contacting scripts-preview@stripe.com.

Stripe 定義の値

Stripe は引数値を提供しますが、カスタマイズすることはできません。関数の実行時に値が提供されます。値には通常、Customer オブジェクトや Line Item オブジェクトなどの Stripe オブジェクトが含まれます。具体的なオブジェクトは、関数インターフェイスによって異なります。必要なデータが見つからない場合は、scripts-preview@stripe.com までお問い合わせください。

Stripe provided parameter example
/**
 * DiscountableLineItem data structure
 *
 * @typedef {Object} DiscountableLineItem
 * @property {MonetaryAmount} subtotal
 * @property {string | null} price_id
 * @property {number | null} quantity
 * @property {MonetaryAmount | null} unit_amount
 * @property {TimeRange} period
 * @property {Price | null} price
 */
export interface DiscountableLineItem {
  subtotal: MonetaryAmount;
  price_id?: string | null;
  quantity?: number | null;
  unit_amount?: MonetaryAmount | null;
  period: TimeRange;
  price?: Price | null;
}

関数ロジック

スクリプト作成者は、スクリプト関数ロジックで使用されるカスタマイズを定義します。すべての引数は「値渡し」であり、関数内で引数値を変更しても、関数外の元の値には影響しません。

実行時エラーを適切に処理する

ほとんどの場合、エラーをキャッチし、フォールバック動作を行います。まれに、例外をスローすることがあります。例外をスローすると、スクリプトに関連付けられているコードの実行全体が停止するため、他のオプションが存在しない場合にのみ例外をスローします。

サンドボックスに対するテストを記述する

スクリプト関数で自動テストスイートを使用することは必須ではありませんが、Stripe では推奨されています。サンドボックス環境に対してテストを記述できますが、レガシーのテストモード環境ではスクリプトはサポートされていません。ガイダンスが必要な場合は、scripts-preview@stripe.com までお問い合わせください。

関数の戻り値

The return value of the function must abide by the interface, which varies by customization. Consult the SDK for the specific interface definition, and make sure your function abides by the interface.

次のステップ

スクリプトクーポンと独自スクリプトの作成方法についてご紹介します。

注