Private preview

Author your own scripts Private preview

Write custom billing logic in TypeScript and run it on Stripe.

Interested in getting early access to script authoring?

Enter your email to request access.

Author custom billing scripts in TypeScript to implement billing logic specific to your business. You write a function that targets a specific billing decision, package it as a Stripe app, and upload it using the Stripe CLI. Stripe runs your script as part of the billing flow. You can create a new script or use a Stripe-authored script as a starting point.

Start building with the step-by-step guide

For a complete walkthrough with prerequisites and CLI commands, see Create a prorations extension with a script. The same steps apply to any billing extension point.

Note

You’re responsible for ensuring your configuration is correct. Stripe doesn’t take responsibility for any issues that arise as a result of your configuration.

In preview, if your script raises an error (for example, returns an invalid result, throws an exception, or times out), Stripe defaults to standard functionality for the operation that caused the failure. If your script encounters a large volume of errors or causes harm, Stripe may disable the script and default to standard functionality for all operations.

Available extension points

Stripe exposes the logic that determines the behavior at specific steps in the billing flow called extension points. You can replace the default logic at these points with your own custom logic. Each extension point defines a typed interface: the inputs Stripe provides to your function and the output your function must return.

For example, when Stripe is about to apply a customer’s balance to an invoice, the customer balance extension point calculates the invoice total and the current balance. Your function decides how much of that balance to apply and returns the amount. Stripe uses your result and continues the billing flow.

When you author a script, you choose which extension point to target. Your function must conform to that extension point’s interface. Each extension point has its own reference page with the full interface definition, input and output types, and example implementations.

This page lists the extension points available for Stripe Billing. For extension points across all Stripe products such as Workflows custom actions and Stripe Open Payments Interface, see Extension points.

Here are the available extension points for billing:

Before you begin

Before you start working with scripts, be aware of their current limitations and their behavior.

Limitations

Scripts currently have the following limitations:

You can only run one script for each billing behavior or extension point at a time.
Scripts only run for subscriptions with flexible billing mode enabled (available for API versions 2025-06-30.basil and later) and pricing plan and license fee subscriptions.
Scripts don’t currently support invoices that require e-mandates for India recurring payments (invoices with INR for their currency).
Scripts don’t affect standalone invoices that aren’t associated with a subscription.
For Checkout Sessions, the logic only runs if mode is set to subscription and billing_mode is set to flexible .
Scripts can’t be shared to connected accounts through Stripe Connect .

Verify your script

When you create your own script, you’re responsible for verifying that your script reflects your intended functionality. Don’t enter any proprietary information, confidential information (for example, PII), or malicious code.

Versioning

When you upload a user-authored script, each upload creates a new version. You can switch between versions at any time from the Billing customizations page.

Switching between script versions takes effect immediately on all future billing operations for that extension point. Invoices and billing events that were already processed under a previous version aren’t retroactively affected. Frequently switching back and forth between versions can introduce inconsistencies in billing behavior across cycles, so we recommend testing new versions thoroughly in a sandbox before going live and minimizing version changes mid-cycle.

Build and upload your script

Scripts are packaged as Stripe Apps. Each app can contain one or more extensions, where each extension targets a specific extension point.

Create a Stripe app using the Stripe CLI.
Generate an extension inside the app for the extension point you want to customize.
Write your logic in TypeScript. Define a configuration schema for any values that are adjustable per instance.
Upload the app using the Stripe CLI.
Test your script in a sandbox . It’s available in the sandbox after you upload it.
For live mode, Stripe reviews your script before it can run on production traffic. After approval, follow the steps to configure a script in the Dashboard to activate it.

For a step-by-step guide with a proration extension example, see Create a prorations extension with a script.