Manage your usage-based billing setup

Learn how to handle billing-related tasks for your usage-based billing model.

After you create your usage-based billing model, you can modify different parts of your billing setup. For example, you can update a subscription item’s price during a billing period, backdate a subscription to include usage in the next invoice, or cancel usage-based subscriptions.

Transform quantities

You can use the transform_quantity option to transform usage before applying the price, which you can use when you want pricing on packages of a product instead of individual units. This allows you to divide the reported usage by a specific number and round the result up or down.

Note

Quantity transformation isn’t compatible with tiered pricing.

For example, say you have a car rental service and you want to charge customers for each hour they rent a car. In this case, you report usage as a number of minutes.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Create a price for the car rental service product. Charge 10 USD per hour, and round up to charge for a full hour, even if the customer uses only part of the hour.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

If a customer rents the car for 150 minutes, that customer is charged 30 USD for 3 hours of rental (2 hours and 30 minutes, rounded up).

Update prices mid-cycle

You can update a subscription item’s price during a billing period.

Flexible billing

When you swap a metered price mid-cycle, we preserve the rate that was active when the usage occurred:

• Pre-swap usage is rated at the old price (for example, 50 events at 1 USD = 50 USD).
• Post-swap usage is rated at the new price (for example, 10 events at 5 USD = 50 USD).

How the pre-swap charge is applied depends on the proration_behavior you specify when updating the subscription item:

• none : No line item is created; the pre-swap amount isn’t charged.
• create _ prorations : A line item for the pre-swap amount is added to the next or period-end invoice.
• always _ invoice : A line item for the pre-swap amount is generated and an invoice is issued immediately at swap time.

Classic billing

With billing_mode=classic subscriptions, pre-swap usage is ignored entirely on future invoices. Only usage reported after the price change is billed, rated at the new price.

For example, say you switch from price A (1 USD per event) to price B (5 USD per event) on January 16. If your customer reported 50 events before the switch and no events after, the end-of-month invoice charges 0 USD—the pre-swap usage isn’t carried forward.

An exception exists if you use billing thresholds and a threshold invoice was already generated at the old price before the swap. That threshold invoice is still charged to the customer. The period-end invoice then includes only usage from January 16 to January 31 at price B, and the threshold invoice doesn’t offset any usage on it.

Similar restrictions apply if you add a new subscription item with a meter price mid-cycle. At the end of the period, the invoice includes only usage from the date you added the item onward, at the new price.

To capture pre-swap usage when changing prices on classic billing, choose one of these options:

• Report the aggregated usage again to capture it in the cycle on the new price.
• Reset the billing_cycle_anchor to now , which closes the current period and bills the old price against usage reported so far.

To update the price for a subscription item:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

To delete a subscription item:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

After deletion, the invoice doesn’t reflect any usage from that item.

Create a backdated subscription

You can record usage for a customer even before creating a subscription for them. After recording usage for a customer, use the backdate_start_date to create a subscription before the first report.

With billing_mode=flexible subscriptions, the subscription’s first invoice includes this backdated usage.

With billing_mode=classic subscriptions, the subscription’s next invoice, generated when it cycles, includes this backdated usage.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Cancel usage-based subscriptions

With usage-based billing, the bill the customer pays varies based on consumption during the billing period. When changing the billing period results in a service period ending early, you charge the customer for the usage accrued during the shortened billing period.

Note

We don’t support proration with usage-based billing.

You can’t reactivate canceled subscriptions. Instead, you can collect updated billing information from your customer, update their default payment method, and create a new subscription with their existing customer record.

If you use cancel_at_period_end to schedule the cancellation of a subscription, you can reactivate the subscription at any time up to the end of the period. To do so, update cancel_at_period_end to false.

For subscriptions that cancel at the end of the period, the final invoice at the end of the period includes metered usage from the last billing period.