Modeling Subscriptions

    Learn how to model subscriptions using Subscription products and plans.

    Products and plans

    Two core models make up Stripe’s recurring billing system: Product and Plan. A Product defines the product or service you offer while a Plan represents how to charge for that Product. The product can be anything you charge for on a recurring basis, such as a digital fax service, 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 plans that define how much and how often to bill for the product. Creating more than one Plan for a Product makes it possible to vary pricing by billing interval (i.e. monthly vs. quarterly billing) or currency. You can even take advantage of this capability to phase out old pricing plans that you’re not offering to new customers.

    Licensed and metered usage

    Plans contain the information for how to price the product: currency, billing interval, amount, and pricing tiers. There are two modes of usage for plans: licensed and metered.

    Licensed (usage_type='licensed') usage 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, i.e. charging $15 per user every month. Subscribing a customer with 3 users to a $15 per-user monthly plan charges that customer $45 every month.

    Metered plans accumulate total 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. Billing for metered plans is calculated the same way as for licensed usage, except the usage total is multiplied by the plan 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 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).

    Questions?

    We're always happy to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

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