Products & plans

A product is what you sell — Starter, Pro, Enterprise. A plan prices that product on a particular cadence in a particular currency. A plan is composed of one or more components, and each component has its own pricing model.

This separation matters: it lets you offer the same product on a monthly plan and an annual plan, in USD and EUR, without duplicating the product itself.

Shape

{
  "id": "prod_…",
  "code": "starter",
  "name": "Starter",
  "description": "For small teams getting started.",
  "metadata": { "category": "self-serve" }
}

{
  "id": "plan_…",
  "code": "starter-monthly-usd",
  "product_code": "starter",
  "currency": "USD",
  "interval": "month",
  "interval_count": 1,
  "components": [
    { "code": "base", "pricing": { "model": "flat", "amount": "29.00" } },
    {
      "code": "seats",
      "pricing": {
        "model": "per_unit",
        "unit_amount": "10.00",
        "included_units": 5,
        "meter": "active_seats"
      }
    }
  ],
  "trial_days": 14
}

The `code` field is your contract

Most APIs accept either the system ID (plan_…) or the human code you defined. Use the code in your application. It’s stable across environments — you’ll have a starter-monthly-usd plan in sandbox and a starter-monthly-usd plan in live, and your code references both with the same string.

Editing a plan

Plans are versioned-by-code. You can:

Add a new component to an existing plan: takes effect on the next billing period for existing subscriptions.
Change the price of a component: takes effect on the next billing period unless you set effective_at to a future date.
Remove a component: takes effect on the next billing period; existing subscriptions get a credit note for any unused portion if prorate is on.

You cannot change the currency or interval of a plan. Create a new plan with a different code instead.

Archiving

Plans have a status: active, archived, deleted.

archived — existing subscriptions keep running; no new subscriptions can be created against this plan code. Useful for grandfathered pricing.
deleted — only allowed if no subscription has ever referenced the plan. Otherwise use archived.

Trials and commitments

Trials and commitments are plan-level defaults that subscriptions inherit. You can override them per subscription when you create it. See Trials & commitments.

Multi-currency

To bill the same product in multiple currencies, create one plan per currency:

starter-monthly-usd
starter-monthly-eur
starter-monthly-gbp

Your application picks the right plan based on the customer’s billing address or chosen currency. Don’t try to use plan-level FX — keep currency explicit at the plan.

Common patterns

If you want	Build
Tiered SaaS pricing	Three plans (Starter / Pro / Business), each with a flat `base` component.
Per-seat pricing	One plan with a `per_unit` component metered by `seats`.
Usage with included quota	One plan with a `per_unit` component, `included_units: N`, plus a `tiered` overage component.
Volume discount	One plan with a `volume` component (entire usage at the tier the total falls into).
Annual discount	A separate plan with `interval: year` and a lower amount.

API surface

Endpoint	Method	What
`/v1/products`	`GET` `POST` `PATCH` `DELETE`	Manage products
`/v1/plans`	`GET` `POST` `PATCH`	Manage plans
`/v1/plans/{id}/components`	`GET` `POST` `PATCH` `DELETE`	Manage components

See Products and Plans for field-level reference.