# Stripe-authored scripts Configure prebuilt scripts to customize billing behavior from the Dashboard. Users should start with a Stripe-authored script before trying to [author their own script](https://docs.stripe.com/billing/scripts/author-your-own.md). > #### Get early access to scripts > > Script authoring is currently in private preview. [Sign up](https://docs.stripe.com/billing/scripts/stripe-authored.md#signup). > > ### Get early access to script authoring > > 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/billing/scripts/stripe-authored" \ -d '{"email": "{{EMAIL}}", "preview": "scripts_preview"}' ``` Stripe provides prebuilt scripts for commonly requested billing customizations. You select a script, adjust its parameters, and activate it from the Dashboard. You don’t have to write any code. Scripts apply at the account level and take effect for all recurring billing logic on the account. Changes take effect on the next billing operation that runs through the configured behavior. To configure and activate any script, see [Configure a script in the Dashboard](https://docs.stripe.com/billing/scripts/configure.md). > You’re responsible for making sure your configuration is correct. Stripe doesn’t take responsibility for any issues that arise as a result of your configuration. > > In preview, if your configuration fails for any reason or causes harm, Stripe reverts to the default feature behavior. To understand the default behavior, see the descriptions of each [available script](https://docs.stripe.com/billing/scripts/stripe-authored.md#available-scripts) (for example, [prorate by custom interval](https://docs.stripe.com/billing/scripts/stripe-authored.md#prorate-by-custom-interval) or [maximum credit per invoice](https://docs.stripe.com/billing/scripts/stripe-authored.md#maximum-credit-per-invoice)). ## Available scripts The following table lists the available Stripe-authored scripts. | Billing behavior | Available scripts | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Proration | - [Prorate by custom interval](https://docs.stripe.com/billing/scripts/stripe-authored.md#prorate-by-custom-interval) - [Credit and debit full product price](https://docs.stripe.com/billing/scripts/stripe-authored.md#credit-and-debit-full-product-price) | | Customer balance | - [Minimum amount before collection](https://docs.stripe.com/billing/scripts/stripe-authored.md#minimum-amount-before-collection) - [Maximum credit per invoice](https://docs.stripe.com/billing/scripts/stripe-authored.md#maximum-credit-per-invoice) | | Item handling | - [Separate invoice for metered items](https://docs.stripe.com/billing/scripts/stripe-authored.md#separate-invoice-for-metered-items) | To write your own script, see [Author your own scripts](https://docs.stripe.com/billing/scripts/author-your-own.md). ## 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](https://docs.stripe.com/billing/subscriptions/billing-mode.md) (available for API versions [2025-06-30.basil](https://docs.stripe.com/changelog/basil/2025-06-30/billing-mode.md) and later) and pricing plan and license fee subscriptions. - Scripts don’t affect standalone invoices that aren’t associated with a subscription. - The custom logic is uploaded to your account and you can’t share it with [connected accounts](https://docs.stripe.com/connect/saas/tasks/create.md) through Stripe Connect. - For Checkout Sessions, the logic only runs if [mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) is set to `subscription` and [billing_mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-billing_mode) is set to `flexible`. - Scripts can’t be shared to connected accounts through [Stripe Connect](https://docs.stripe.com/connect.md). - Third-party libraries aren’t supported as dependencies. ### Fallback behavior If Stripe-authored scripts fail to run for any reason, Stripe reverts to the default behavior for that billing step. ### Versioning When you first activate a Stripe-authored script on an extension point, you’re automatically placed on the latest available version. As Stripe releases new versions, you can upgrade at your own pace. You can also revert to a previous version if needed. 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. ## Proration Use the following scripts to customize billing behavior for prorations. ### Prorate by custom interval By default, Stripe calculates proration down to the second when a subscription triggers prorations. This script rounds proration to a larger time unit you choose, so the prorated amounts on the invoice are clean and predictable. Use this script whenever your business needs proration calculated in units larger than a second, whether to match regional billing conventions, align with contractual terms, or reduce customer confusion caused by fractional amounts. #### Configuration options 1. Select **Customize** next to **Proration**. 1. Select **Prorate by custom interval**. 1. Set the **Granularity**, which is the time unit used to round proration. 1. Set the **Rounding mode**, which controls which direction to round when a mid-cycle change falls between two granularity boundaries. Day boundaries align to the subscription’s billing period start time, not midnight. 1. Select **Save** and confirm activation. | Value | Description | | ----- | --------------------------------------- | | Hour | Proration is calculated in whole hours | | Day | Proration is calculated in whole days | | Week | Proration is calculated in whole weeks | | Month | Proration is calculated in whole months | Select the granularity that matches how your business defines billing periods in contracts or invoices. | Mode | What happens | Effect | | ----------------------------- | -------------------------------------------------------------- | ------------------------------------------------------ | | Round to the nearest interval | Rounds to the nearest boundary. If exactly halfway, rounds up. | Closest approximation to actual usage. | | Always round up | Always rounds up to the next boundary. | The customer stays on the old price for the full unit. | | Always round down | Always rounds down to the previous boundary. | The customer moves to the new price for the full unit. | Round to the nearest interval is the most common choice for businesses that want the closest approximation to actual usage. Interval boundaries are anchored to the subscription’s billing start date and time. By default, this is the exact time the subscription is created. It changes if you set a specific start date during creation, add a free trial (boundaries align to the trial end date and time), or reset the billing cycle when updating an existing subscription (boundaries align to the exact time of the reset). Boundaries are time zone-agnostic. When a mid-cycle change happens between two boundaries, the rounding mode determines which boundary the change snaps to. #### Example A customer starts a 30 USD per month Basic plan on April 1 at 12:00 AM (billing period: April 1 through May 1, 30 days). The customer upgrades to a 60 USD per month Premium plan on April 11 at 6:00 AM. Custom interval is set to Day, rounding mode is set to `Round to nearest interval`. **Default behavior** Stripe prorates to the second. The invoice shows fractional amounts. - Credit (old plan): 19.75 USD - Charge (new plan): 39.50 USD **After activating the script** The subscription started on April 1 at 12:00 AM, so each day boundary falls at 12:00 AM. The two nearest boundaries to the upgrade are April 11 at 12:00 AM and April 12 at 12:00 AM, with the midpoint at April 11 at 12:00 PM. Since 6:00 AM is before the midpoint, `Round to nearest interval` snaps to the earlier boundary (April 11 at 12:00 AM), giving 20 full days remaining. - Credit (old plan): 20.00 USD (20 days at 30 USD per month) - Charge (new plan): 40.00 USD (20 days at 60 USD per month) To see the change in the Dashboard: 1. Select a subscription. 1. Select **Update subscription**. 1. Preview the proration amounts on the **Invoice** tab before finalizing. 1. View the generated invoice on the **Invoices** tab after the change is applied. ### Credit and debit full product price By default, when a subscription changes mid-cycle, Stripe prorates all items on the subscription based on the time remaining in the billing period. This script overrides that behavior for specific products by refunding or charging the full price instead of the prorated amount. You control which products are exempt from proration by tagging them with metadata. Metadata is a set of custom labels you can attach to objects in Stripe. Each label has two parts: a key (the name of the label) and a value (what the label is set to). You choose any key and value that makes sense for your business. When the script runs during a mid-cycle change, it checks each product’s metadata. If a product’s metadata matches the key and value you configured in the script, that product is charged and credited in full instead of being prorated. Use this script when certain products on a subscription aren’t prorated. For example, a flat support fee or a platform access charge that’s always billed in full regardless of when the subscription changes. #### Configuration options 1. Select **Customize** next to **Proration**. 1. Select **Credit and debit full product price**. 1. Set **Product metadata key**, which is the metadata key to check on the Product object. 1. Set **Product metadata value**, which is the value that marks a product as exempt from proration. 1. Select **Save** and confirm activation. Before activating, add the metadata key-value pair to each product you want to exempt: 1. In the Dashboard, go to **Product catalog**. 1. Open the product. 1. Go to **Metadata** > **Add metadata** and enter the key-value pair you configured in the script. 1. Click **Save**. Repeat for each product you want to exempt. Products without this metadata are prorated with the default behavior. #### Example A customer is on a 40 USD per month plan and upgrades to an 80 USD per month plan on day 15 of a 30-day billing period. The script is configured with a metadata key `full_swap` and value `true`. The 80 USD per month product has this metadata set. The 40 USD per month product doesn’t. With the Stripe default by-the-second proration: - Credit for unused time on the old plan: -19.87 USD - Debit for remaining time on the new plan: +39.73 USD - Net charge: 19.86 USD With this script: - Credit for unused time on the old plan: -19.87 USD (default proration, no metadata) - Debit for the full new plan amount: +80.00 USD (`full_swap`: true) - Net charge: 60.13 USD ## Customer balance Use the following scripts to customize billing behavior for customer balances. ### Minimum amount before collection By default, when a customer has a [balance](https://docs.stripe.com/billing/customer/balance.md), Stripe applies the full amount to the next invoice. This script lets you set a minimum charge threshold. When the total owed (invoice total plus customer balance) is below the threshold, Stripe negates the invoice’s total amount due by deferring the amount to the customer’s balance for the next billing cycle. When the total meets or exceeds the threshold, Stripe applies the full balance and collects payment. Use this script to avoid collecting on small invoices by deferring them to the customer balance until the total owed reaches a threshold you define. Use it when you want to accumulate charges across billing cycles before collecting, or avoid charging customers for small amounts. #### Configuration options 1. Select **Customize** next to **Customer balance**. 1. Select **Minimum amount before collection**. 1. Set the **Minimum amount**, which is the minimum amount (in the currency’s minor unit) the total owed must reach before Stripe collects payment. For example, setting `10000` in USD means the total must reach 100 USD before collection. 1. Select **Save** and confirm activation. #### Example Configure this script with a threshold amount and currency. When the total owed (invoice amount plus customer balance) is below the threshold, the invoice is zero-charged and the full amount rolls to the customer balance for the next billing cycle. When the total meets or exceeds the threshold, the full customer balance is applied and the customer is charged. In this example, a customer has a 30 USD debit balance and receives a 20 USD invoice. The script is configured with a threshold of 100 USD. The total owed would be 50 USD, which is below the threshold, so the invoice is zero-charged and the 50 USD carries to the next cycle. If instead the invoice were 80 USD, the total would be 110 USD, which exceeds the threshold, so the full balance is applied and the customer is charged 110 USD. **Scenario 1: Below threshold** - Invoice total: 20 USD - Customer balance: 30 USD debit - Total owed: 50 USD (below the 100 USD threshold) **Result:** Stripe debits the invoice total of 20 USD to the customer’s balance, which results in a 0 USD amount due for this invoice. No payment is collected this cycle. **Scenario 2: At or above threshold** - Invoice total: 80 USD - Customer balance: 30 USD debit - Total owed: 110 USD (above the 100 USD threshold) **Result:** Stripe applies the full 30 USD balance. The customer is charged 110 USD. New balance: 0 USD. To see the change in the Dashboard, review the invoice after the billing cycle runs. On the invoice detail page, check the line items and the customer balance transaction to confirm whether the charge was collected or deferred. ### Maximum credit per invoice By default, Stripe applies the full customer credit balance to each invoice, reducing the amount due. This script lets you configure a maximum amount of credit that can be applied to a single invoice. Any remaining credit stays on the customer’s balance for future invoices. Use this script when you want to spread credits across multiple billing cycles instead of applying them all at once, or when business rules require limiting credit usage per invoice. #### Configuration options 1. Select **Customize** next to **Customer balance**. 1. Select **Maximum credit per invoice**. 1. Set the **Maximum credit amount**, which is the maximum amount of credit (in the currency’s smallest unit) that can be applied to a single invoice. For example, setting `10000` in USD means at most 100 USD of credit can be applied per invoice. 1. Select **Save** and confirm activation. #### Example Configure this script with a maximum credit amount and currency. When a customer has a credit balance, the script caps how much of that credit can be applied to a single invoice. In this example, a customer has a 500 USD credit balance and receives a 200 USD invoice. The script is configured with a limit of 50 USD. Only 50 USD of credit is applied, so the customer pays 150 USD. The remaining 450 USD in credit stays on the balance for future invoices. **Default behavior** Stripe applies the full 150 USD of available credit to the invoice. - Credit applied: 150 USD - Customer pays: 0 USD - Remaining credit balance: 50 USD **After activating the script** Stripe applies only 100 USD of credit to the invoice. - Credit applied: 100 USD - Customer pays: 50 USD - Remaining credit balance: 100 USD To see the change in the Dashboard, review the invoice after the billing cycle. Check the customer balance transaction on the invoice detail page to confirm how much credit was applied. ## Item handling Use the following scripts to customize billing behavior for item handling. ### Separate invoice for metered items By default, when a subscription contains both metered usage items and licensed items, Stripe puts them all on a single invoice. This script routes them to separate invoices based on the item’s usage type. The invoice with licensed items becomes the latest invoice for the subscription. Use this script when your finance team needs to reconcile usage charges separately from recurring seat or license fees, or when your customers expect different invoices for them. #### Configuration options 1. Select **Customize** next to **Item handling**. 1. Select **Separate invoice for metered items**. 1. Select **Save** and confirm activation. This script has no additional parameters. It automatically routes items based on their usage type. #### Example A subscription includes a “Pro Plan” licensed at 20 USD per month and metered API usage totaling 15 USD this billing cycle. **Default behavior** One invoice with both items. - Invoice total: 35 USD (20 USD license + 15 USD usage) **After activating the script** Two separate invoices. - Invoice 1 (licensed): 20 USD for Pro Plan. This invoice becomes the subscription’s latest invoice. - Invoice 2 (metered): 15 USD for API usage. To see the change in the Dashboard, go to the subscription detail page and check the **Invoices** tab to see two invoices for the billing period instead of one. ## See also - [Customize billing with scripts](https://docs.stripe.com/billing/scripts.md) - [Author your own scripts](https://docs.stripe.com/billing/scripts/author-your-own.md) - [Configure a script in the Dashboard](https://docs.stripe.com/billing/scripts/configure.md)