Products and Plans

Products are a new concept introduced in the Billing (formerly, Subscriptions) API.

Products are your new entry-point to modeling what you sell and how you charge for it. A Product can be anything for which you charge. For simple billing needs, you can represent your entire offering (like a video-on-demand streaming service), or a portion of a complex product offering, with many features. Consider a phone service, for example, that charges a fee per phone line but also tracks data usage and out-of-country calls during a billing period to charge for them at the end. All three of these items—the phone line fee, the broadband usage, and the out-of-country calling—would each be represented by a Product.

Dashboard Changes

Although no changes are required to your API integration, your dashboard experience will change to match Stripe’s new model.

Subscriptions becomes Billing

‘Billing’ replaces the ‘Subscriptions’ sidebar link. You can still find all of the information about your subscriptions here, but there is now an upgraded invoicing product that allows you to more easily send ad-hoc invoices to your customers.

Plans become Products with Plans

Nested in the Billing sidebar, there is a Products section.

If you are upgrading from an earlier version of the API, all of your existing plans have a corresponding product in the product list. When you navigate into a particular product, it lists the pricing plans for that product. If you upgraded from an API version earlier than 2018-02-05, each Product has exactly one Plan.

When your pricing needs expand, you can add more pricing plans to your products to implement pricing experiments or to vary pricing by region or currency. You can find more in-depth descriptions on the modeling and products and plans pages.

API Changes

The APIs have undergone a number of changes that make it easier for users to implement their desired billing models.

The API to create subscriptions for your customers has not changed in version 2018-02-05. You won’t be required to change the way you create subscriptions after the upgrade. However, with tiered pricing, you may find it easier to model your pricing by changing your product and plan structure.

Updating your API version

Product

Product is a new concept in the Billing API. A Product is a description of anything for which you charge. In practice, for simple billing structures, it serves as a description of your actual product. For complex billing structures, it may just describe a portion of the services that you bill every period.

• type (required). The type of Product to create. Stripe’s Billing API only supports products with type=service.
• name (required). The name of the Product. The name of the Product appears on your customer’s invoices and receipts. This field was extracted from Plan and moved to Product. To change what appears on your customer’s invoices and receipts, change the product name.
• statement_descriptor (optional). The description that shows up on your customer’s credit card statement. This field was extracted from Plan and moved to Product
• unit_label (optional). Only used when billing using a Plan with usage=metered. The unit label describes the units of the item being charged for, i.e. megabyte(s), test message(s), or carwash(es).

New Plan fields

• product (required). Creating a Plan requires a product. The Product describes what you’re charing for. The Plan defines the pricing of the product. Using an API version of 2018-02-05 or greater, you can define many pricing plans for the same product.
• usage_type (optional). When usage_type=licensed, the plan uses subscription item quantity to calculate the line item total for an invoice. This is the behavior you are accustomed to for plans. If usage_type is omitted, licensed is the default behavior. When usage_type=metered, the plan uses Usage accumulated during the billing interval to calculate the total for an invoice.
• billing_scheme (optional). When billing_scheme=per_unit, amount must be specified—and, at the end of the billing period, the plan will be multiplied by the subscription item quantity or Usage to calculate the total for an invoice. This is the behavior you’re accustomed to. If billing_scheme is omitted, per_unit is the default behavior. When billing_scheme=tiered, then tiers must be specified and the subscription item quantity or Usage is used to calculate pricing based on the configured tiers.
• tiers_mode (optional). Only applies when billing_scheme=tiered. Chooses between graduated and volume pricing. See tiers documentation for more details.
• transform_usage (optional). Allows you to report usage at a different rate than you bill. See usage transformation for more details.
• nickname (optional). An internal identifier for the plan to make it distinguishable from other plans. Though optional, we don’t recommend creating plans without a nickname.

Removed Plan fields

• name. The name that appears on your customer’s receipts and invoices has been moved to the Product.
• statement_descriptor. The description that appears on your customer’s credit card statements has been moved to the Product.

Taking into account all of the changes, this is an example of creating a plan with the new API, assuming the Product already exists:

curl https://api.stripe.com/v1/plans \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d nickname="New pricling plan" \
   -d product="{{EXISTING_PRODUCT_ID}}" \
   -d amount=1000 \
   -d currency=usd \
   -d interval=month \
   -d usage_type=licensed

As a convenience, you can specify Product fields inline to create a plan with a new Product:

curl https://api.stripe.com/v1/plans \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d nickname="Shiny new plan" \
   -d product[name]="Fancy New Product" \
   -d product[statemend_descriptor]="FANCY PRODUCT" \
   -d amount=1000 \
   -d currency=usd \
   -d interval=month \
   -d usage_type=licensed

How to test

Test your API integration by explicitly specifying thee Stripe-Version header in your test mode API requests, as shown in the versioning documentation. Stripe versions 2018-02-05 or greater support the new Product and Plan API changes.

Many prices for a Product

The largest functional difference in version 2018-02-05 is the ability to represent multiple prices for the same product. Multiple Plans for a Product are only available from API version 2018-02-05. Until you upgrade your API Version to 2018-02-05 or later, you won’t be able to add multiple plans to the same product from the dashboard.