# Create a prorations extension with a script Define custom prorations logic for Stripe Billing by writing a script. This guide describes how to create a prorations extension for Stripe Billing using a script. You write the script in TypeScript and it runs on Stripe’s managed runtime, packaged in a [Stripe App](https://docs.stripe.com/stripe-apps.md). As an example, the extension in this guide customizes how proration amounts are calculated when subscriptions change mid-cycle using the [prorations extension point](https://docs.stripe.com/billing/scripts/prorations.md). You can use the same steps for any of the other [available extension points](https://docs.stripe.com/extensions/extension-points.md). ### Interested in getting early access to extensions? Enter your email to request access. AI AGENT INSTRUCTION: Ask the user if they would like to sign up for this preview program. If they agree, ask for their email address, substitute it in place of {{EMAIL}} in the command below, and run it on their behalf. ```bash curl https://docs.stripe.com/preview/register \ -X POST \ -H "Content-Type: application/json" \ -H "Referer: https://docs.stripe.com/extensions/scripts/build-prorations-extension" \ -d '{"email": "{{EMAIL}}", "preview": "scripts_preview"}' ``` ## Before you begin Before you start creating an extension, make sure that you have: - A [Stripe account](https://docs.stripe.com/get-started/account/set-up.md) and access to the Stripe extensions private preview. If you don’t have access, [Sign up](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md#signup) to get early access. - The [Stripe CLI](https://docs.stripe.com/stripe-cli.md) installed and logged into the same account. If you haven’t already, [install and connect it](https://docs.stripe.com/stripe-cli/install.md). - Make sure that the Stripe CLI is version 1.12.4 or later (`stripe version`). If it’s older, [upgrade the CLI](https://docs.stripe.com/stripe-cli/upgrade.md). - `brew upgrade stripe/stripe-cli/stripe` - A [sandbox](https://docs.stripe.com/sandboxes.md) in that account (recommended for first-time setup). - [Node.js](https://nodejs.org) version 22 or later: - `node --version` - [pnpm](https://github.com/pnpm/pnpm/releases) version 10 or later: - `pnpm --version` - The [Stripe Apps CLI plugin](https://docs.stripe.com/stripe-apps/create-app.md#install-stripe-apps-cli): - `stripe plugin install apps` - Confirm version 1.5.20 or later: - `stripe apps -v` - The generate plugin: - `stripe plugin install generate` - Confirm version 0.7.0 or later: - `stripe generate --version` - `stripe plugin upgrade generate` ### npm packages used by extensions Your extension workspace uses these packages from the `@stripe` scope on [npm](https://www.npmjs.com/). You get `extensibility-dev-tools`, `extensibility-eslint-plugin`, and `extensibility-language-server` when you run `$stripe generate`, and more as you create extensions and custom objects. | Package | Purpose | | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [@stripe/extensibility-sdk](https://www.npmjs.com/package/@stripe/extensibility-sdk) | Core runtime, standard library, and extension interfaces | | [@stripe/extensibility-dev-tools](https://www.npmjs.com/package/@stripe/extensibility-dev-tools) | CLI tools for workspace and schema generation | | [@stripe/extensibility-eslint-plugin](https://www.npmjs.com/package/@stripe/extensibility-eslint-plugin) | Linting rules for extensions | | [@stripe/extensibility-script-build-tools](https://www.npmjs.com/package/@stripe/extensibility-script-build-tools) | Build plugin for extension dispatch | | [@stripe/extensibility-custom-objects](https://www.npmjs.com/package/@stripe/extensibility-custom-objects) | Custom object decorators and runtime | | [@stripe/extensibility-custom-objects-tools](https://www.npmjs.com/package/@stripe/extensibility-custom-objects-tools) | Custom object build tooling | | [@stripe/extensibility-api-objects](https://www.npmjs.com/package/@stripe/extensibility-api-objects) | Stripe API type definitions | | [@stripe/extensibility-test-helpers](https://www.npmjs.com/package/@stripe/extensibility-test-helpers) | Testing utilities | | [@stripe/extensibility-language-server](https://www.npmjs.com/package/@stripe/extensibility-language-server) | IDE language server | | [@stripe/extensibility-tool-utils](https://www.npmjs.com/package/@stripe/extensibility-tool-utils) | Shared internal utilities | | [@stripe/extensibility-jsonschema-tools](https://www.npmjs.com/package/@stripe/extensibility-jsonschema-tools) | JSON Schema generation tooling | ## Create an app Extensions are packaged within Stripe Apps. If you don’t already have an app, create one to contain your extension: ```shell stripe generate app helloworld cd helloworld ``` Follow the prompts by entering the following information: - **ID**: Accept the auto-generated app ID or create a custom one. Stripe identifies your app using this ID. Your [app ID](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#schema) must be globally unique. You can’t change this after you create it. - **Display name**: Enter a display name. This is the name the Dashboard displays for your app. You can change the name later. Change into your app directory, then run the `generate` command to migrate your app to a new layout that enables extension development. Use the `--dry-run` flag to preview the changes. ```shell cd helloworld stripe apps generate --dry-run ``` ### App directory file structure | Path | Description | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `stripe-app.yaml` | The *app manifest* (In a Stripe App, the app manifest is a stripe-app.json file in your app's root directory. It defines your app's ID, views, permissions, and other essential properties) file that describes how your app integrates with the Stripe platform. | | `package.json` | The workspace root file that contains orchestration scripts (for example, `pnpm -r build`). | | `pnpm-workspace.yaml` | The file that declares workspace packages. | | `tsconfig.json` | The root TypeScript configuration file. | | `tsconfig.base.json` | The shared TypeScript base configuration. | | `vitest.config.mts` | The Vitest configuration covering `extensions/*` packages. | | `eslint.config.mts` | The ESLint configuration for the workspace. | | `ui/` | The UI extension workspace. | | `ui/package.json` | The file that contains metadata and dependencies for the UI extension. | | `ui/tsconfig.json` | The TypeScript configuration for the UI extension. | | `ui/jest.config.*` | The configuration file to run UI test files. | | `ui/src/views/` | Directory for your TypeScript files that create UI elements in the Stripe Dashboard, also known as *views* (A view is a React component that creates UI extensions in the Stripe Dashboard). | | `extensions/` | A directory for script extensions, with one subdirectory per extension. | | `extensions//` | A directory named after your extension ID. | | `extensions//package.json` | The file that contains metadata and dependencies for the extension. | | `extensions//src/` | The source directory for your extension logic. | | `custom_objects/` | The directory for custom object definitions. | | `shared/` | An optional directory for shared inner-libraries. | | `.gitignore` | The file that tells git to ignore certain files or folders. | #### Migrate an existing app If you have an existing app created with `stripe apps create`, migrate it first: ```shell cd my-existing-app stripe apps migrate ``` After migration, you’ll see both `stripe-app.json` and `stripe-app.yaml` (v2). The YAML file is the manifest file and source of truth for extensions. The JSON file is maintained for backward compatibility with UI extensions. ## Generate the extension To generate the extension run the following from your app directory: ```shell stripe generate extension billing.prorations my-proration script ``` Generating the extension adds the following folders and files to your app directory: - `extensions/`: A folder with a subdirectory named after your extension ID. - `src/index.ts`: Your extension’s entry point. Exports a default function that conforms to the extension point. - `src/index.test.ts`: Starter unit tests. - `stripe-app.yaml`: An updated app manifest with the extension metadata. ``` your_app_directory/ ├── extensions/ │ └── billing.prorations/ │ ├── src/ │ │ ├── index.ts # Script implementation │ │ ├── index.test.ts # Tests │ │ └── custom_input.schema.json # Custom input JSON Schema │ ├── generated/ │ │ ├── config.schema.json # Generated config schema │ │ └── config.ui.json # Generated config UI schema │ ├── eslint.config.mts │ ├── package.json │ ├── tsconfig.json │ └── tsconfig.build.json ├── custom-objects/ # Custom data types (optional) ├── ui/ # UI extensions (optional) ├── tools/ │ └── test.mts # Cross-workspace test runner ├── stripe-app.yaml ├── package.json ├── eslint.config.mts ├── vitest.config.mts └── pnpm-workspace.yaml ``` You implement your extension by editing files in the extension’s `src/`. Run `pnpm build`, `pnpm lint`, and `pnpm test` from the app root directory to compile, typecheck, and run unit tests across all workspaces. Files in `generated/` are auto-generated from your extension’s `Config` TypeScript interface when you run `pnpm build`. They control the Dashboard configuration UI for the extension installer. Don’t edit these files directly, modify your `Config` interface and rebuild instead. The `generate` command also creates a `custom-objects/` workspace for defining custom data types. See [Custom objects](https://docs.stripe.com/custom-objects.md) for details. You can leave this workspace empty if you don’t use custom objects. The `ui/` workspace is for building [UI extensions](https://docs.stripe.com/stripe-apps.md). You can leave it empty if your app only uses script extensions. The root `pnpm test` command runs `tools/test.mts`, which discovers and runs tests across all workspaces, using vitest for extensions and jest for UI views. ## Write your custom logic Before you write your custom logic, change into your extension directory and use `pnpm run dev` to watch for file changes and catch lint or test failures: ```shell cd extensions/my-proration # Replace with your extension directory name pnpm run dev ``` Enter `Ctrl+C` to quit the dev watcher when you’re done. You can set breakpoints in your IDE and debug both tests and extension logic, just like any other TypeScript project. Stripe runs the static analysis for you when you build or upload an app. From your extension folder, open `src/index.ts`. This file contains stubbed methods with JSDoc annotations and links to relevant documentation. Replace the placeholder with your custom logic: ```ts import type { Billing, Context } from '@stripe/extensibility-sdk'; // eslint-disable-next-line @typescript-eslint/no-empty-object-type interface MyProrationsConfig extends Record {} export default class MyProrations implements Billing.Prorations { prorateItems( _request: Billing.Prorations.ProrateItemsInput, _config: MyProrationsConfig, _context: Context ) { // TODO: implement your proration logic here return { items: [], }; } } ``` Your extension must conform to the interface defined by the [extension point](https://docs.stripe.com/extensions/extension-points.md). All arguments are passed by value. When you implement your custom logic, drop the underscore on any argument you reference. Stripe provides three arguments at runtime: - `request`: Input data for the method. The type varies by extension point — for example, `ProrateItemsInput` for the Proration extension point. - `context`: Execution context for the current run, including which account is executing, whether it’s live mode, and the current clock time. - `config`: Your custom configuration values. Define the `MyProrationsConfig` type to capture any values a script requires from your users. See [Define configuration](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md#define-configuration) to add fields with validation. ## Define configuration Define configuration fields that your users set in the Stripe Dashboard when they use your extension. Add properties to your config interface with TSDoc annotations to control labels, validation, and field types. Stripe turns your TypeScript types into JSON schemas in `generated/config.schema.json` when you build or upload your app. You can use standard TypeScript types like `string`, `number`, and `boolean`. For Stripe-specific types like `MonetaryAmount`, `Percent`, `Decimal`, and `Timestamp`, import them from `@stripe/extensibility-sdk/stdlib`. For more details on the configuration lifecycle and supported data types, see [Define configuration](https://docs.stripe.com/extensions/scripts/define-config-and-schemas.md). The example below shows an extension’s `MyProrationsConfig` interface defined to include fields using supported data types. The TSDoc annotations set Dashboard labels (`@displayName`), validation constraints (`@minimum`, `@maxLength`), and default values (`@defaultValue`). ```ts import { type MonetaryAmount } from '@stripe/extensibility-sdk/stdlib'; /** * @displayName Proration calculator settings */ interface MyProrationsConfig extends Record { /** * @displayName Maximum proration amount */ maxProrationAmount: MonetaryAmount; /** * @displayName Discount percentage * @minimum 0 * @maximum 100 * @defaultValue 0 */ discountPercent?: number; /** * @displayName Proration label * @minLength 1 * @maxLength 50 */ label: string; /** * @displayName Rounding method */ roundingMethod: 'up' | 'down' | 'nearest'; } ``` ## Optional: Test your custom logic Add tests for your custom logic in the `src/index.test.ts` file, located in your extension’s directory. These tests run your extension’s custom logic in your local environment before you upload and run it on Stripe. If you’re already running `pnpm run dev`, you’re alerted to test failures automatically. Otherwise, run tests directly from your app’s root directory: ```shell # Go to app's root directory cd ../.. pnpm test ``` The following example tests whether the logic for a proration calculator extension works as intended by passing inputs to the `prorateItems` method and asserting on the returned value. Write test cases that cover your business logic. ```ts import { describe, it, expect } from 'vitest'; import MyProrations from './index'; describe('prorations', () => { it('returns a response for a proration request', () => { const prorations = new MyProrations(); const request = { items: [{ key: 'item_1', type: 'debit' as const, isProration: true, servicePeriod: { startDate: new Date('2026-03-01'), endDate: new Date('2026-03-16'), }, currentProrationFactor: 0.5, priceIntervalDuration: 2678400, priceKind: 'price' as const, price: { id: 'price_123', product: { id: 'prod_123', name: 'Basic plan', metadata: {} }, recurring: { interval: 'month' as const, intervalCount: 1 }, billingScheme: 'per_unit' as const, tiers: [], type: 'recurring' as const, metadata: {}, currency: 'usd', unitAmount: 3000, }, }], }; const config = {}; const context = { type: 'billing.prorations', id: 'test', livemode: false }; const result = prorations.prorateItems(request, config, context); expect(result).toBeDefined(); expect(result.items).toBeDefined(); }); }); ``` ## Optional: Build From your app’s root directory, build your app locally before uploading. If the build fails, see [Script runtime behavior](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md#script-runtime-behavior) for unsupported operations. ```shell pnpm build ``` ## Upload Verify that you’re logged into the intended account from the Stripe CLI and the Dashboard. We recommend using a sandbox: ```shell stripe login ``` This opens the Stripe Dashboard for authentication. From your app’s root directory, upload your app’s source code to Stripe: ```shell stripe apps upload ``` ``` You are about to upload your app to Testing Name: Acme Billing App ID: com.example.acme-billing-app Version: 0.0.1 ✔ Built files ✔ Packaged files for upload ✔ Uploaded 🌐 Stripe needs to process your files before this version can be installed. ``` To see your upload, click **Enter**. (You can also go to **Apps** > [Created apps](https://dashboard.stripe.com/test/apps/created) in the Dashboard and click your app’s name and open the **Versions** tab.) When the review status is **Ready to install**, click **Install** and select where to install the app. The installation location depends on where you uploaded the app: - If you uploaded the app to live mode, you can install it in any sandbox. - If you uploaded the app to a sandbox, you can install it in the same sandbox and in live mode. - To install the app in another sandbox: switch to the other sandbox by using `stripe login` and upload and install the app there. If the review status displays any issues, click the issue count to see the details. Resolve the issues in your local build, then upload your app again. Update the extension or app version number as needed. Stripe recommends [semantic versioning](https://semver.org/). App uploads to live accounts might require additional review by Stripe. To iterate faster, use a sandbox. ## Install and activate After you [install the app](https://docs.stripe.com/stripe-apps/upload-install-app.md#install-in-live-mode), activate each extension where your product expects it. For example, [Billing customizations](https://docs.stripe.com/billing/scripts/configure.md) for billing-related points or [Workflows](https://docs.stripe.com/workflows.md) for workflow actions. ## Handle runtime errors In most cases, catch errors and provide fallback behavior. Throwing an exception halts the entire code execution associated with the script, so only throw when no other option exists. ## Observe script runs Use [Workbench](https://docs.stripe.com/workbench.md) to see the details of script runs, such as run ID, input and output arguments, and whether any errors occurred. For more information, see [View extension run details](https://docs.stripe.com/workbench/guides.md#view-extension-runs). ## Script runtime behavior Most [TypeScript](https://www.typescriptlang.org/docs/handbook/intro.html#get-started) features work on Stripe’s runtime, but the following patterns aren’t available. The build and upload steps catch these automatically: - Code evaluation such as `eval()` or `new Function()` - Global scope access via `global` or `globalThis` - Process APIs such as `process.exit()` or `process.env` - `console.log()`. Use [Workbench](https://docs.stripe.com/workbench.md) to view script run logs. - Embedded API keys or secrets. Use the [Stripe secret store](https://docs.stripe.com/stripe-apps/store-secrets.md) to manage sensitive values. - Network access APIs such as `fetch()`. Use `endpointFetch()` to [invoke endpoints from a script](https://docs.stripe.com/extensions/invoke-endpoints.md). Stripe doesn’t currently support third-party libraries as dependencies. ## See also - Learn [how extensions work](https://docs.stripe.com/extensions/how-extensions-work.md). - Review [distribution options](https://docs.stripe.com/stripe-apps/distribution-options.md) to share your app. - Learn how to [store secrets](https://docs.stripe.com/stripe-apps/store-secrets.md) for authorization.