A plan is a reusable pricing template that defines what a customer gets and how they're charged. Plans combine one or more products with pricing rules and are attached to subscriptions.
Plans support versioning - when you update a plan's pricing or product lineup, existing subscribers stay on their current version until explicitly migrated. This lets you iterate on pricing without disrupting active subscriptions.
Key concepts:
- Products - the items included in this plan, each with optional included quantities and rollover rules
- Versions - immutable snapshots of the plan configuration at a point in time
- Publishing - makes a draft plan version available for new subscriptions
- Migration - moves existing subscribers from one plan version to another, with configurable proration
List plans
Returns a paginated list of plans with optional status and custom field filters
query Parameters
limitPage size
cursorPagination cursor
statusFilter by status
List plans › Responses
Paginated list with data and pagination envelope
archived_atcreated_atdeleted_atdeprecated_atdescriptionexternal_idhead_version_ididnameorganization_idpublic_descriptionpublished_atpublished_byrequires_continuous_coveragestatusupdated_atversionCreate a plan
Creates a new plan in draft status
Create a plan › Request Body
descriptionexternal_idnamepublic_descriptionCreate a plan › Responses
Wrapped in data envelope
archived_atcreated_atdeleted_atdeprecated_atdescriptionexternal_idhead_version_ididnameorganization_idpublic_descriptionpublished_atpublished_byrequires_continuous_coveragestatusupdated_atversionUpdate a plan
Updates an existing plan by UUID
path Parameters
idPlan UUID
Update a plan › Request Body
descriptioneffective_atADR-0006 edit-as-publish controls.
expected_versionexternal_idnameProductVersionPins lets the operator override which product version each attached product is pinned to when this publish snapshots the plan. Map shape: product_id → product_version_id. Missing products (i.e. attached but not in the map) snap at the product's current head as before — so this field is purely additive: nil ≡ today's behaviour, non-nil applies the override per entry. Mirrors the products-page ChildVersionPins payload. The publish path validates every entry against the plan's attached products and the referenced product_versions row.
public_descriptionsave_as_draftstatusUpdate a plan › Responses
Wrapped in data envelope
archived_atcreated_atdeleted_atdeprecated_atdescriptionexternal_idhead_version_ididnameorganization_idpublic_descriptionpublished_atpublished_byrequires_continuous_coveragestatusupdated_atversionMigrate plan subscribers
Previews or executes subscriber migration to a new plan version
path Parameters
idPlan UUID
Migrate plan subscribers › Request Body
modeproration_strategyscheduled_attarget_versionMigrate plan subscribers › Responses
Wrapped in data envelope
Add a product to a plan
Adds a product to the specified plan
path Parameters
idPlan UUID
Add a product to a plan › Request Body
included_quantityproduct_idrollover_enabledrollover_expiry_periodsrollover_maxAdd a product to a plan › Responses
Wrapped in data envelope
created_atidincluded_quantityorganization_idplan_idproduct_idrollover_enabledrollover_expiry_periodsrollover_maxList plan versions (with lifecycle filter)
Returns version rows for a plan. Status filter accepts DRAFT, SCHEDULED, ACTIVE, SUPERSEDED, CANCELLED. Default excludes DRAFT and CANCELLED.
path Parameters
idPlan UUID
query Parameters
statusLifecycle status filter (repeatable)
List plan versions (with lifecycle filter) › Responses
OK
archived_reasoncreated_atcreated_byeffective_fromeffective_toidID is the *_versions.id UUID. Phase 2.D needs it so the FE stage-mode chip can wire selection→pin map without a separate number→ID lookup; older clients can ignore the field.
published_atstatususage_countversionGet a plan version snapshot
Returns the historical snapshot of the given plan version (same shape as GET /plans/{id}).
path Parameters
idPlan UUID
versionVersion number
Get a plan version snapshot › Responses
OK
idorganization_idplan_idpublished_atversion