A plan's price, currency, billing interval and entitlement rules live on its versions. A published version never changes: to change any of these, you publish a new version of the same plan. Your code does not change either, because it names capability keys, never plans or versions.
Change a price or an allowance
In the operator console, under Products & Plans, open the plan and choose Create Next Draft. Through the Management API, the steps are:
| Step | Endpoint |
|---|---|
| Create the next draft, copied from the plan's latest version | POST /mgt/v1/projects/{projectId}/plans/{planId}/versions |
| Change the price, currency, billing interval or overage discount | PATCH /mgt/v1/projects/{projectId}/plans/{planId}/versions/{version} |
| Replace the entitlement rules | PUT /mgt/v1/projects/{projectId}/plans/{planId}/versions/{version}/rules |
| Publish | POST /mgt/v1/projects/{projectId}/plans/{planId}/versions/{version}/publish |
Changing a published version is refused with VERSION_IMMUTABLE, and publishing one again with VERSION_ALREADY_PUBLISHED.
Save the draft before you publish
In the console, choose Save Draft after changing a draft's rules, and only then Publish Version. A rule added and published without saving is left out of the published version.
What publishing does
Publishing freezes the version: its price, its rules and the overage price of each rule, worked out as described in Plan versions and entitlement rules. From then on the version is the one the public catalog offers for that plan.
What happens on Stripe depends on whether the application has a payment connection:
| Payment connection | When you publish |
|---|---|
| Connected | ShipRev first creates the matching product and price on your Stripe account, then freezes the version. If Stripe does not accept them, the version stays a draft and nothing is frozen; publish again once the cause is fixed |
| Not connected yet | The version is frozen at once and waits to be synced. When you connect an account, every version waiting is synced in the same request; if one fails, the connection is still saved, the rest keep waiting, and saving the connection again retries them. Versions of archived plans are not synced |
A version that waits to be synced can be subscribed to without a card when its plan allows it, but not through checkout: checkout needs the Stripe price.
What existing subscribers get
Nothing changes for them. A subscription points at the version it was taken on, so a subscriber keeps that version's price, rules and overage prices, and their renewals in Stripe continue on that version's price. Their entitlements are not rebuilt when you publish.
New subscribers get the latest published version, because that is the version the public catalog and PricingTable offer for the plan.
An existing subscriber moves to the new version only by changing plan themselves. PricingTable lists each plan with its latest version, so a subscriber on an older version of Pro sees Pro as a plan they can switch to; the switch is charged like any other plan change, as described in Change plan. Moving existing subscribers to a new version in bulk is not available.
Retire a plan
Archive the plan, in the console with Archive Plan or with POST /mgt/v1/projects/{projectId}/plans/{planId}/archive. It disappears from the public catalog and takes no new subscriptions; subscriptions already on its versions carry on. A plan with a published version cannot be deleted.