# Proration

Configure Stripe-authored scripts to customize proration behavior.

### Interested in getting early access to Stripe-authored scripts?

Enter your email to request access.

```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/proration" \
  -d '{"email": "EMAIL", "preview": "scripts_preview"}'
```

Use the following scripts to customize billing behavior for prorations.

> 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 customization fails for any reason or causes harm, Stripe reserves the right to default to standard functionality and/or pause subscription processing. To understand the default behavior, see the descriptions of each [available script](https://docs.stripe.com/billing/scripts/stripe-authored.md#use-cases).

## 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**.
2. Select **Prorate by custom interval**.
3. Set the **Granularity**, which is the time unit used to round proration.
4. 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.
5. 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.
2. Select **Update subscription**.
3. Preview the proration amounts on the **Invoice** tab before finalizing.
4. 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**.
2. Select **Credit and debit full product price**.
3. Set **Product metadata key**, which is the metadata key to check on the Product object.
4. Set **Product metadata value**, which is the value that marks a product as exempt from proration.
5. 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**.
2. Open the product.
3. Go to **Metadata** > **Add metadata** and enter the key-value pair you configured in the script.
4. 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

## See also

- [Stripe-authored scripts](https://docs.stripe.com/billing/scripts/stripe-authored.md)
- [Configure a script in the Dashboard](https://docs.stripe.com/billing/scripts/configure.md)
- [Customize subscription proration calculations](https://docs.stripe.com/billing/scripts/prorations.md)