---
title: How the catalog becomes a subscription
description: How products, prices, and subscription items fit together, and what a customer is charged at signup.
domain: subscription
status: shipped
visibility: public
last_verified: 2026-08-28
order: 25
---
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.

```viz catalog-to-subscription
```

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.

```viz subscription-anatomy
```

- 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](/guide/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](/guide/billing-timing/in-advance-and-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.

```viz signup-charges
```

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](/guide/usage/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](/guide/product-catalog/products). 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](/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.