Plans

A plan is one priced offering of a product, in one currency, on one interval. See Products & plans and Pricing models for the model.

Object

{
  "id": "plan_…",
  "object": "plan",
  "code": "pro-monthly-usd",
  "product_code": "pro",
  "currency": "USD",
  "interval": "month",
  "interval_count": 1,
  "trial_days": 14,
  "tax_behavior": "exclusive",
  "components": [
    {
      "code": "base",
      "pricing": { "model": "flat", "amount": "49.00" }
    },
    {
      "code": "seats",
      "pricing": {
        "model": "per_unit",
        "unit_amount": "10.00",
        "included_units": 5,
        "meter": "active_seats"
      },
      "tax_code": null
    }
  ],
  "dunning_policy": null,
  "metadata": {},
  "status": "active",
  "created_at": "2026-05-06T12:34:56Z",
  "updated_at": "2026-05-06T12:34:56Z"
}

Endpoints

Method	Path	What
POST	/v1/plans	Create.
GET	/v1/plans/{code-or-id}	Retrieve.
PATCH	/v1/plans/{code-or-id}	Update mutable fields.
GET	/v1/plans	List.
POST	/v1/plans/{code-or-id}/components	Add a component.
PATCH	/v1/plans/{code-or-id}/components/{component_code}	Update a component.
DELETE	/v1/plans/{code-or-id}/components/{component_code}	Remove a component.

Immutable fields

currency, interval, interval_count, code, product_code. Need a different value? Create a new plan.

Mutable fields

trial_days, tax_behavior, dunning_policy, metadata, status, components (via the component sub-resource).

Component shape

Each component has:

• code (slug, unique within the plan)
• pricing (one of the pricing model shapes — see Pricing models)
• tax_code (optional override)

Components are independent; their amounts sum to the invoice subtotal.

Component changes and existing subscriptions

Adding, removing, or repricing a component affects existing subscriptions on the next billing period by default. To delay:

PATCH /v1/plans/{code}/components/{component_code}
{ "pricing": { … }, "effective_at": "2026-07-01T00:00:00Z" }

The change is queued and applied to subscriptions whose period starts after effective_at.

Status

status	Meaning
active	Subscribable.
archived	Existing subscriptions keep running; no new subscriptions can be created.
deleted	Only allowed if no subscription has ever referenced the plan.

Archive almost always; delete almost never.

Webhook events

plan.created, plan.updated, plan.archived.