Plans, add-ons and charges
The three kinds of catalog item, how groups organize them, and which add-ons go with which plans.
Everything you sell lives in the catalog, and every catalog item is one of three kinds. The kind decides how the item behaves when you bill it.
The three kinds
| Kind | What it is |
|---|---|
| Plan | The recurring base of a subscription. A subscription is built on a plan. |
| Add-on | A recurring extra attached alongside a plan, like an extra feature or seat pack. |
| Charge | A one-time item, like a setup fee or an implementation service. Billed once, on an invoice. It never repeats. |
A subscription is anchored by a plan, with add-ons riding alongside it. A charge is billed once: put it on a subscription, at signup or later, and it is queued in full as a pending charge and billed on that subscription's next invoice, never prorated and never repeated. Until it bills, you can void it from the subscription's unbilled charges. A charge can also go straight onto a one-off invoice.
Groups
A group organizes the catalog into product lines: say a CRM group and a Helpdesk group, each holding its own Starter, Pro and Enterprise plans. Groups are purely visual. They section the catalog list and pickers, and they never limit what a subscription can contain or which plan a customer can change to. If you're coming from a system with "product families", note the difference: a group won't block a plan change the way a family wall does.
A subscription is one plan, plus any add-ons. Each line points at a price. One-time charges are billed on invoices instead.
The page on how the catalog becomes a subscription walks through how these fit together and what a customer is charged at signup.
Which add-ons go with which plans
Every add-on has an availability setting, managed on the add-on's own page. It has two modes:
- Available on all plans. The default. Any subscription can add it, and new plans include it automatically.
- Only on selected plans. The add-on lists the plans that accept it, and subscriptions on other plans won't see it.
Selecting the first plan is what switches an add-on from the first mode to the second, and the app says so before it happens. Each plan's page mirrors the same setting: it shows every add-on a subscription on that plan can carry, including the all-plans ones. From there you can also add an already-limited add-on to the plan; limiting an all-plans add-on for the first time happens on the add-on's own page, since that changes where it is offered everywhere.
This keeps your catalog coherent: a seat pack meant for the Team plan will not accidentally end up on a Starter subscription.
In the API
Catalog items are created through the POST /v1/products endpoint. The API calls them products, and the kind values are plan, addon, and one_off (shown in the app as Plan, Add-on, and Charge). A group is the category field. Prices are created separately; see prices and the API reference.
Edge cases
- A subscription needs a plan. Add-ons and charges attach to a subscription, but the plan is what a subscription is built on.
- Charges are not metered. A one-time charge is a fixed thing you bill once, not something measured over a period.
- Compatibility is an allow-list. It says which add-ons may go on a plan. It does not force any add-on onto a subscription.