How the catalog becomes a subscription
How products, prices, and subscription items fit together, and what a customer is charged at signup.
The catalog and a subscription connect through one simple chain: a product has prices, and a subscription is a set of items, where each item points at a price. This page walks that chain from the catalog to the first invoice, with a picture at each step.
A product has prices; an item picks one
You do not put a product on a subscription directly. You put a price on it. A product can have several prices, and a subscription item points at the exact one the customer chose.
So "Pro plan, billed monthly in dollars" is a price. The subscription item holds that price, and from then on the item bills the way that price says.
A subscription is a plan plus extras
A subscription is not a single thing. It is a bundle of items: one plan, plus any add-ons. Each item is its own line, with its own price and its own quantity.
A subscription is one plan, plus any add-ons. Each line points at a price. One-time charges are billed on invoices instead.
- The plan is the foundation. Every subscription has one.
- Add-ons ride alongside the plan, each billing on its own price. Extra seats, a premium feature, a support tier.
Each item can carry a quantity, like 5 seats. For a flat or per-unit item, you can also override the price with a negotiated amount for that one subscription, without changing the catalog.
How each item bills
Every item follows its own price, so a single subscription can mix billing styles:
- The pricing model on each item's price decides how its amount is worked out: flat, per unit, tiered, and the rest. See pricing models.
- The billing timing on each item's price decides whether it charges at the start or the end of the period. See in advance or in arrears.
So a plan billed in advance can sit next to a usage add-on billed in arrears, on the same subscription.
What is charged at signup
When the subscription starts, the first invoice bills the items that charge in advance: the plan, and any add-ons that bill up front. A one-time charge on the subscription is on that first invoice too, in full, and only there. If the subscription starts with a trial, the charge waits and bills on the first paid invoice at trial end.
A usage add-on would not appear here. Usage is billed in arrears, after the period.
Usage add-ons do not appear on this first invoice. Usage is billed in arrears, so it lands on a later invoice once there is usage to bill. See recording usage.
In the app and the API
You build a subscription in the app by choosing a plan price, adding add-ons, and setting the quantity on each. A one-time charge can be added to the subscription through the API, where it is queued and billed once on the next invoice, or billed directly on a one-off invoice; see plans, add-ons and charges. The same thing is available through the API: the POST /v1/subscriptions endpoint takes the customer and a list of items, each naming a price. See the API reference for the full request.
Edge cases
- A subscription always has a plan. Add-ons are extras on top of it.
- Each item bills on its own terms. Model and timing come from each item's price, not from the subscription as a whole.
- A negotiated amount is per subscription. Overriding a flat or per-unit price for one customer does not touch the catalog price other customers use.