How to model subscriptions

    Learn how to model subscriptions using subscription products and prices.

    Products and prices

    Subscriptions consist of two core models: Products and Prices. A Product defines the product or service you offer, while a Price represents how to charge for that Product. The product can be anything you charge for on a recurring basis, such as a digital SaaS product, a base fee for phone service, or a service that comes to your home and washes your car every week.

    Products have no pricing information. Instead, the Product has one or more prices that define how much and how often to bill for the product. Creating more than one Price for a Product makes it possible to vary pricing by billing interval (e.g., monthly or quarterly billing) or currency. You can even take advantage of this capability to phase out old prices that you’re not offering to new customers.

    Licensed and metered usage

    Prices define how to charge for a product: currency, billing interval, amount, tiers, etc. For subscriptions, prices have two types: licensed and metered.

    Licensed (recurring[usage_type]='licensed') allows you to set the number of units for a subscription item when creating or updating the subscription. Once the quantity for a subscription item is set, it persists until it is explicitly changed. Every billing interval, the subscription charges amount × quantity for the item. This is commonly known as seat-based pricing (e.g., charging $15 per user every month). Subscribing a customer with 3 users to a $15 per-user monthly subscription charges that customer $45 every month.

    Metered billing accumulates usage over a billing period. Usage is reported via the Usage API and resets to zero every billing period. A broadband provider charging per megabyte of usage every month, for example, would use metered billing. With metered billing, the total is calculated the same way as for licensed usage, except the usage total is multiplied by the price unit_amount instead of using a fixed quantity.

    Tiered billing

    More complex pricing schemes are expressed through tiered pricing (billing_scheme='tiered') which can be combined with either licensed or metered usage.

    Tiered pricing allows you to change the cost per item as quantity or usage increases. Imagine a chat service that charges $2 per user for the first 10 users, then $1 per user for each user beyond the first 10. This can similarly be applied to metered billing: a broadband provider could charge $30 for the first gigabyte of usage and then 50 for every subsequent gigabyte.

    Metered billing calculates your customer’s charge by totaling usage over a billing period. There are three modes of metered billing:

    • Fixed per-unit pricing by setting billing_scheme to per_unit. The total at the end of the period is unit_amount × usage.
    • Volume-based pricing by setting billing_scheme to tiered and setting tiers_mode to volume. The total at the end of the period is the amount for the specific tier × usage. For example, given a tiering configuration of $5 for usage of 1 - 5, $4 for 6 - 10, and $3 for 11 - 20, a usage of 11 would result in a total of $33 ($3 × 11).
    • Graduated pricing by setting billing_scheme to tiered and setting tiers_mode to graduated. The total at the end of the period is the sum of the amount for each tier × the usage for that particular tier. For example, given a graduated tiering configuration of $5 for usage of 1 - 5, $4 for 6 - 10, and $3 for 11 - 20, a usage of 11 would result in a total of $48 ($5 × 5 + $4 × 5 + $3 × 1).

    Packaged vs standard pricing

    In the Dashboard, you may notice the option of adding a price that is either packaged or standard as a price model.

    These map to Licensed (recurring[usage_type]='licensed'), which allows you to set the number of units for a subscription item when creating or updating the subscription. Package allows you to set the quantity per unit to be something above 1 where as standard defaults to 1 quantity per unit.

    Was this page helpful?

    Feedback about this page?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page