Program your business logic directly on Stripe with scriptsPrivate preview

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

• Define your own logic for specific Stripe objects
• Tailor your Stripe account for your specific business needs
• Extend Stripe beyond its standard functionality

For example, you can use scripts to create custom discount logic on new coupons, and then apply the coupons to Subscriptions and Invoices.

Script lifecycle

See the following script lifecycle to understand how to use scripts:

• Start by authoring custom logic for a supported use case.
• As part of script-authoring, you can define configuration values. These are parameters that a script user passes when creating a custom object.
• Stripe registers your script on the script service after you submit it for review.
• You can then invoke the script when creating objects, such as a Coupon or Subscription object.

Function arguments

You can place the argument of the functions into two categories:

Author-defined values

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 author 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).

The script author decides what parts of the script to make customisable for the script user. The script user then applies their own values to the customisable parts of the script.

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.

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-defined values

Stripe provides argument values, and you can’t customise them. We provide the values at function runtime, and they typically include Stripe objects such as the Customer or Line Item objects. The specific objects vary by function interface. If you’re missing any data you need, contact scripts-preview@stripe.com.

/**
 * 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;
}

Function logic

The script author defines the customisation used by the script function logic. All arguments are “pass by value,” which means any modifications made to the argument values within the function don’t affect the original value outside the function.

Handling runtime errors appropriately

In most cases, you want to catch the error and have fallback behaviour. In rare cases, you might want to throw an exception. Throwing an exception halts the entire code execution associated with the script, so only throw an exception when no other option exists.

Write tests against your sandbox

Although we don’t require you to use an automated test suite with your script function, we recommend it. You can write tests against your sandbox environment, but the legacy test mode environment doesn’t support scripts. If you need guidance, contact scripts-preview@stripe.com.

Function return value

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

Next steps

Learn more about script coupons and how to author your own scripts.