# Model usage-based pricing

Learn about different pricing models for usage-based billing on Stripe.

> We’ve updated the way usage-based billing works. See the [updated usage-based billing docs](https://docs.stripe.com/billing/subscriptions/usage-based.md).
> 
> Learn how to [migrate](https://docs.stripe.com/billing/subscriptions/usage-based-legacy/migration-guide.md).

With usage-based pricing models, you charge your customers based on how much of your service they use during the billing period, instead of explicitly setting quantities, as in the [per-seat](https://docs.stripe.com/products-prices/pricing-models.md#per-seat) and [flat rate](https://docs.stripe.com/products-prices/pricing-models.md#flat-rate) pricing models. (Another difference is that in the per-seat and flat-rate models, you could optionally collect payment for the billing period up front. With usage-based billing, you have to collect payment in arrears.) You must also [record and report usage](https://docs.stripe.com/billing/subscriptions/usage-based-legacy/recording-usage.md).

In this case, the business wants to charge on a per-minute basis for usage of their new conferencing service, where more usage drives the per-minute price lower for the customer.

Here’s what that model looks like on Stripe:
![](https://b.stripecdn.com/docs-statics-srv/assets/pricing_model-metered-usage.43b16d41d299829bc3fd34ddc2d14b15.png)

Usage-based pricing model

### Usage types

For recurring purchases, you define how much to charge customers through `usage_types`-either licensed or metered.

### Licensed usage

With licensed usage (`recurring[usage_type]='licensed'`), you set the quantity for a subscription item when you create or update the subscription. The quantity persists until you or your customer changes it. Every billing period, the subscription charges the amount × quantity for the item. For example, a customer with three users who subscribes to a 15 USD per-user monthly service pays 45 USD every month.

### Metered usage

With metered usage (`recurring[usage_type]='metered'`), you bill your customer in arrears based on how much of your service they consume and track their usage with the [Usage API](https://docs.stripe.com/api/usage_records.md). At the end of the billing period, the total usage is multiplied by the `unit_amount` to calculate how much the customer owes. For example, if a broadband provider charges 0.50 USD per gigabyte (GB) used, and a customer uses 100 GB, they charge the customer 50 USD.

### Package and standard pricing 

In the Dashboard, you can select **Standard pricing** or **Package pricing** as pricing models. Both of these models map to the [licensed](https://docs.stripe.com/api/prices/create.md#create_price-recurring-usage_type) (`recurring[usage_type]='licensed'`) usage type. With both models, you specify the number of units when you create or update a subscription. Here’s how they differ:

- With **Standard pricing**, the quantity defaults to 1.
- With **Package pricing**, you set the unit amount to values of 2 or more.

### Model usage-based pricing on Stripe

The following example shows how to create a metered usage pricing model. In this case, the service charges .07 USD per minute.

#### Dashboard

To create a metered usage pricing model on Stripe through the Dashboard:

First, create the `Per-minute pricing` product. To learn about all the options for creating a product, see the [prices guide](https://docs.stripe.com/products-prices/manage-prices.md#create-product).

1. Go to the [Product catalog](https://dashboard.stripe.com/products).
1. Click **+ Add product**.
1. Enter the **Name** of the product: `Per-minute pricing`, in this case.
1. (Optional) Add a **Description**. The description appears at checkout, on the [customer portal](https://docs.stripe.com/customer-management.md), and in [quotes](https://docs.stripe.com/quotes.md).

Next, create the monthly price for the `Per-minute pricing` product.

Click **Advanced pricing options**. Select **Usage-based**, **Per tier**, and **Graduated** for the **Pricing model**.

Select **Graduated pricing** for the **Pricing model**, then select **Recurring**.

Create three graduated pricing tiers:

|               | First unit | Last unit | Per unit | Flat rate |
| ------------- | ---------- | --------- | -------- | --------- |
| For the first | 0          | 60        | 0.25 USD | 0.00 USD  |
| For the next  | 61         | 120       | 0.20 USD | 0.00 USD  |
| For the next  | 121        | ∞         | 0.15 USD | 0.00 USD  |

Then, select **Monthly** for the **Billing period** and check **Usage is metered**.

To create a subscription using that price:

1. Go to the **Payments** > **Subscriptions** [page](https://dashboard.stripe.com/subscriptions).
1. Click **+ Create subscription**.
1. Find or add a customer.
1. Search for the `Per-minute pricing` product you created and select the price you want to use.
1. (Optional) Select **Collect tax automatically** to use Stripe Tax.
1. Click **Start subscription** to start it immmediately or **Schedule subscription** to choose when to start it.

#### API

To create a metered usage pricing model on Stripe through the [Products](https://docs.stripe.com/api/products.md) and [Prices](https://docs.stripe.com/api/prices.md) APIs:

1. Create the `Per-minute pricing` product.

   ```curl
   curl https://api.stripe.com/v1/products \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d name="Per-minute pricing"
   ```

1. Create a price.

   ```curl
   curl https://api.stripe.com/v1/prices \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d nickname="Per-minute pricing" \
     -d "tiers[0][unit_amount]"=500 \
     -d "tiers[0][up_to]"=5 \
     -d "tiers[1][unit_amount]"=400 \
     -d "tiers[1][up_to]"=10 \
     -d "tiers[2][unit_amount]"=100 \
     -d "tiers[2][up_to]"=inf \
     -d currency=usd \
     -d "recurring[interval]"=month \
     -d "recurring[usage_type]"=metered \
     -d product="{{PRODUCT_ID}}" \
     -d tiers_mode=graduated \
     -d billing_scheme=tiered \
     -d "expand[0]"=tiers
   ```

When you create subscriptions, use the ID of the graduated tiered price:

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer={{CUSTOMER_ID}} \
  -d "items[0][price]"={{PER_MINUTE_PRICE_ID}}
```

The subscription integration guide explains how to fit pricing models into a full integration.

- If you’re using Stripe Checkout, the next step is to [create a Checkout session](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md?payment-ui=checkout&ui=stripe-hosted#create-session) for your site. Make sure you set up Stripe.
- If you’re using Stripe Elements, the next step is to [create a Customer](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md?payment-ui=elements&api-integration=checkout#create-customer). Make sure you set up Stripe and the sample application.

For other versions of usage-based pricing, see the [advanced](https://docs.stripe.com/billing/subscriptions/usage-based-legacy/pricing-models.md#advanced) models section. Also learn how to set up [free trials](https://docs.stripe.com/billing/subscriptions/usage-based-legacy.md#trials) and other optional features for a usage-based billing integration.

## Advanced pricing models 

### Flat rate and per-seat 

You can subscribe the customer to two separate products to model a pricing structure that includes both a base fee and additional per-seat pricing. One product serves as the flat base price and the other product represents the variable per-seat pricing.

This example company charges a flat monthly rate for their service plus a tiered price for more than 50 users.

#### Model flat rate and per-seat on Stripe 

To model this structure on Stripe, the example company creates a **Product** and **Price** for the base fee:

```curl
curl https://api.stripe.com/v1/prices \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d nickname="Monthly Base Fee" \
  -d product={{BASE_FEE_PRODUCT_ID}} \
  -d unit_amount=500 \
  -d currency=usd \
  -d "recurring[interval]"=month \
  -d "recurring[usage_type]"=licensed
```

Then they create a monthly price that charges 15 USD per user:

```curl
curl https://api.stripe.com/v1/prices \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d nickname="Per-seat price" \
  -d product={{PRODUCT_ID}} \
  -d unit_amount=1500 \
  -d currency=usd \
  -d "recurring[interval]"=month \
  -d "recurring[usage_type]"=licensed
```

Here’s how they subscribe a customer with three users to the base fee price and the per-user price:

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer="{{CUSTOMER_ID}}" \
  -d "items[0][price]"={{BASE_FEE_PRICE_ID}} \
  -d "items[0][quantity]"=1 \
  -d "items[1][price]"={{PER_SEAT_PRICE_ID}} \
  -d "items[1][quantity]"=3
```

This results in a 50 USD charge every month: the 5 USD base monthly rate, plus 15 USD each for 3 users.

### Flat rate with usage-based pricing 

You can also combine flat rates with usage-based pricing to charge a flat monthly rate in addition to charging for usage over the billing period.

To create a flat rate with a usage-based pricing model on Stripe through the [Products](https://docs.stripe.com/api/products.md) and [Prices](https://docs.stripe.com/api/prices.md) APIs:

1. Create the `Flat monthly fee` product.

   ```curl
   curl https://api.stripe.com/v1/products \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d name=Per-seat
   ```

1. Create a price for the `Flat monthly fee` product.

   ```curl
   curl https://api.stripe.com/v1/prices \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d product="{{PRODUCT_ID}}" \
     -d unit_amount=1000 \
     -d currency=usd \
     -d "recurring[interval]"=month
   ```

1. Create the `Meeting per minute usage` price.

   ```curl
   curl https://api.stripe.com/v1/prices \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d nickname="Metered Monthly Plan" \
     -d product={{PRODUCT_ID}} \
     -d unit_amount=700 \
     -d currency=usd \
     -d "recurring[interval]"=month \
     -d "recurring[usage_type]"=metered
   ```

When you create subscriptions, specify both price IDs:

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer="{{CUSTOMER_ID}}" \
  -d "items[0][price]"={{FLAT_MONTHLY_FEE_PRICE_ID}} \
  -d "items[0][quantity]"=1 \
  -d "items[1][price]"={{METERED_USAGE_PRICE_ID}} \
  -d "items[1][quantity]"=1
```

### Decimal amounts 

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.

#### Creating objects with decimal amounts 

To [create prices](https://docs.stripe.com/api.md#create_price) 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](https://docs.stripe.com/products-prices/pricing-models.md#tiered-pricing), you can specify `unit_amount_decimal` instead of `unit_amount`. You can also [create invoice items](https://docs.stripe.com/api/invoiceitems/create.md) with `unit_amount_decimal` instead of `unit_amount`.

In API responses, the integer `unit_amount` field isn’t populated if the object is created 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 instance, if you create a price with `unit_amount_decimal = 5`, the response contains `unit_amount = 5` and `unit_amount_decimal = 5.0`.

> If your integration has event handling that uses `unit_amount` values and you begin using decimal amounts, you need to use `unit_amount_decimal` instead. This is important because `unit_amount` will be returned as `null` if the decimal amounts can’t be converted into integers, which could cause errors in your integration.