Model usage-based pricing

You can use trial periods for subscriptions with usage-based billing. During the trial period, any usage accrued doesn’t count toward the total charged to the customer at the end of the billing cycle. After the trial period ends, usage accrues and is billed at the end of the next billing cycle.

Learn more about trial periods and subscriptions.

Webhooks and trials

Make sure that your integration properly monitors and handles web events related to changes in trial status.

A few days before a trial ends and the subscription moves from trialing to active, you receive a customer.subscription.trial_will_end event. When you receive this event, make sure that you have a payment method on the customer’s account to proceed with billing them. Optionally, notify the customer in advance about the upcoming charge.

Learn more about subscriptions and webhooks.

With usage-based billing, the bill the customer pays varies based on consumption during the billing cycle. When changing the billing cycle results in ending a subscription interval early, you charge the customer for the usage accrued during the shortened billing cycle. We don’t support proration with usage-based billing.

After a subscription is canceled, you can’t reactivate it. 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.

After you schedule the cancellation of a subscription using cancel_at_period_end, you can reactivate it at any point up to the end of the period by updating cancel_at_period_end to false. The final invoice includes any metered usage after the subscription cancels at the end of the billing period.

Use the transform_quantity option to transform usage before applying the price. This allows you to divide the reported usage by a specific number and round the result either up or down. This is commonly used when pricing on packages of a product instead of individual units. Quantity transformation isn’t compatible with tiered pricing.

For example, let’s say you have a car rental service. You report usage as a number of minutes, and you want to charge customers for each hour the car is rented.

curl https://api.stripe.com/v1/products \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d name="Car Rental Service"

Next, create a price for the car rental service product, charging 10 USD an hour and rounding up (to charge for a full hour even if only part of the hour is used):

curl https://api.stripe.com/v1/prices \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d nickname="Car Rental Per Hour Rate" \
  -d unit_amount=1000 \
  -d currency=usd \
  -d "recurring[interval]"=month \
  -d "recurring[usage_type]"=metered \
  -d product={{CAR_RENTAL_SERVICE_PRODUCT_ID}} \
  -d "transform_quantity[divide_by]"=60 \
  -d "transform_quantity[round]"=up

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

Decimal pricing is useful if you need to create pricing amounts that aren’t whole numbers. For example, if you’re running a cloud storage SaaS business, you can create a price that charges 0.05 cents for each MB used per month. Based on usage, the quantity of MB is then multiplied by 0.05 cents and rounded to the nearest whole cent.

To create prices with decimal amounts, specify unit_amount_decimal instead of unit_amount. unit_amount_decimal allows you to set the amount in the minor unit of the currency that you charge in. For example, you can set unit_amount_decimal = 105.5 in USD to represent 105.5 cents, or 1.055 USD. unit_amount_decimal accepts decimals up to 12 decimal places.

If you plan to use tiers, you can specify unit_amount_decimal instead of unit_amount. You can also create invoice items with unit_amount_decimal instead of unit_amount.

In API responses, the integer unit_amount field doesn’t populate if you create the object with a decimal value. For example, if you create a price with unit_amount_decimal = 0.05, the response contains unit_amount = null and unit_amount_decimal = 0.05. You can still pass integer values into unit_amount_decimal, in which case unit_amount is populated in the response. For example, if you create a price with unit_amount_decimal = 5, the response contains unit_amount = 5 and unit_amount_decimal = 5.0.

By default, Stripe finalizes subscription invoices one hour after they’re generated. During this one hour grace period, you can continue to report usage for the previous period. When the invoice finalizes, we update it to reflect the latest quantity for its billing period.

Usage reported after the invoice finalizes aren’t captured in future invoices.

You can configure a longer grace period.

You can update a subscription item’s price during a billing cycle. However, the following limitations apply when switching from one billing meter price to another:

• We only reflect usage occurring after the update on future invoices. Usage occurring before the change won’t be invoiced. For example, if you have a monthly subscription that you switch from price A to price B on Jan 16th, then at the end of the month the invoice generated accounts for usage from Jan 16th to Jan 31st at price B. Usage from Jan 1st to Jan 16th isn’t billed.
• There’s one exception to this rule if you use billing thresholds and have a threshold invoice already generated at the old price. For example, in the above scenario, if you had a threshold invoice generated on January 10th using price A, that threshold invoice is still charged to the customer. At the end of the month, the invoice generated accounts for usage from January 16th to January 31st at price B. The earlier threshold invoice does not offset any usage for this end-of-month invoice.
• Similar restrictions apply if you add a new subscription item with a billing meter price in the middle of the subscription cycle. For example, if you add a new subscription item with price C on Jan 16th, then at the end of the month the invoice generated accounts for usage from Jan 16th to Jan 31st at price C for that subscription item.

Here’s how you can update price for a subscription item:

curl https://api.stripe.com/v1/subscription_items/{{SUBSCRIPTION_ITEM_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d price={{NEW_PRICE_ID}}

To delete a subscription item:

curl -X DELETE https://api.stripe.com/v1/subscription_items/{{SUBSCRIPTION_ITEM_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

After deletion, we don’t reflect any usage from that item on the invoice.

You can report usage for a customer even before creating a subscription for them. After reporting usage for a customer, you can use backdate_start_date to create a subscription before the first report, ensuring that the usage is included in the next subscription invoice.

curl -X POST https://api.stripe.com/v2/billing/meter_events \
  -H "Authorization: Bearer 
{{YOUR_API_KEY}}
" \
  -H "Stripe-Version: 2024-11-20.acacia" \
  --json '{
    "event_name": "alpaca_ai_tokens",
    "payload": {
        "value": "25",
        "stripe_customer_id": "{{CUSTOMER_ID}}"
    },
    "timestamp": "2024-04-01T12:00:00.000Z"
  }'

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d customer={{CUSTOMER_ID}} \
  -d "items[0][price]"={{PRICE_ID}} \
  -d backdate_start_date=1710000000