This page explores some common billing use cases and demonstrates how to model them with products and prices. The following examples follow a fictional company, SqueakyCar, that’s offering a car wash service. Washers come to the customer’s home to wash their cars.
Simple monthly billing
Many businesses begin with a simple monthly rate or “per-seat” pricing. This is modeled by specifying the
unit_amount on a Price. Specify a
quantity when creating a subscription to charge for multiple seats or licenses.
SqueakyCar’s new car wash service charges 20 USD per car each month. First, they create a
Product to describe what they’re selling—in this case, a weekly car washing service:
Next, they add a price to the product. The following example shows how to add a price that bills 20 USD per month:
This example demonstrates how to create a subscription to SqueakyCar’s service for a customer with two cars, specifying
Products can use multiple prices to define different pricing options. The product description is shared between prices and appears the same on the customer’s receipt and invoice—only the pricing differs.
As SqueakyCar’s product matures, they begin offering the same product at different price points. Specifically, certain customers are willing to pay for discounted up-front quarterly and yearly subscriptions. SqueakyCar creates a quarterly 57 USD option:
And a yearly 220 USD option:
As SqueakyCar expands to different markets, such as Canada, they can add prices in different currencies:
And the UK:
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.
SqueakyCar has seen a boom in multi-car households, so they are changing their pricing to introduce a new base fee that they will charge their customers alongside the per-car monthly fee. They create a
Price for the base fee:
And a monthly price that charges 15 USD per car:
The following example demonstrates how to subscribe a customer with three cars to the base fee price and the per-car price:
This results in a 50 USD charge every month: the 5 USD base monthly rate, plus 15 USD each for 3 cars.
Metered billing is useful in cases where you want to charge your customers a granular amount based on their consumption of your service during the billing cycle, instead of explicitly setting quantities. For example, SqueakyCar can use metered billing to offer a service where they wash their customer’s cars as needed, and charge at the end of the month for the total number of washes.
The following example shows how to set the value of
usage_type to create a price with metered billing. In this case, they charge 7 USD per car wash:
Metered billing can also be applied in situations where the unit you are measuring is not strictly based on a sum. For example, imagine that in addition to car washing, SqueakyCar also rents out garage parking spots to their customers, and wants to charge for the maximum number of parking spots used per customer per month. SqueakyCar can configure this with the
Imagine that a customer has two cars parked on June 1st, then parks a third car on the 15th, and later removes one of the first two cars on the 20th. The billed amount at the end of the month is 600 USD (three cars maximum usage during the month, charging 200 USD per car).
Usage-based pricing can also be combined with flat fees (as shown above) to charge a flat monthly rate in addition to charging for usage over the billing cycle.
Prices can represent tiers, allowing the unit cost to change with quantity or usage. SqueakyCar might, for example, want to offer lower rates for customers who use more washes per month. The following examples show two different ways to adjust pricing as usage increases: volume-based pricing and graduated pricing. To demonstrate these approaches to tiered pricing, we will use the following tiers:
|Number of car washes||Price per wash|
|1 - 5||7 USD|
|6 - 10||6.50 USD|
With volume-based pricing, the subscription item is billed at the tier corresponding to the amount of usage at the end of the period. To implement volume-based billing tiers, set
volume as the value of
Under volume-based pricing, a customer with 5 car washes is charged 35 USD at the end of the period: 7 USD for each of the 5 washes. However, if they accumulate 6 washes the following month, then all washes are billed at the
6-10 rate. That month, they are charged 39 USD (6.50 × 6).
While similar to volume pricing, graduated pricing charges for the usage in each tier instead of applying a single price to all usage. Set the value of
graduated to use graduated tiers:
With graduated pricing, 5 car washes result in the same charge as volume-based pricing—35 USD total at 7 USD per wash. This changes as usage breaks out of the first tier. A customer with more than 5 washes is charged 7 USD per wash for the first 5 washes, then 6.50 USD for washes 6 through 10, and finally 6 USD per wash thereafter. A customer with 6 car washes would be charged 41.50 USD, 35 USD for the first 5 washes and 6.50 USD for the 6th wash.
transform_quantity option to aggregate usage before multiplying by unit cost. This is useful if you want to report a different quantity or usage before totaling price.
SqueakyCar decided to expand their car wash offerings with a premium waxing service. Car waxing can be time consuming, so they charge an extra usage fee (another
Product) based on the time washers spend waxing the car. Washers report the exact amount of time spent waxing the cars, but SqueakyCar doesn’t want to charge customers by the minute. Instead, they will charge for each hour spent waxing—even a partial hour.
First, create the premium waxing product:
Next, price the waxing service, charging 5 USD an hour and rounding up (to charge for a full hour even if only part of the hour is used):
If a washer spends 150 minutes waxing a customer’s cars, that customer would be charged 15 USD for 3 hours of waxing (2 hours and 30 minutes, rounded up).