Plans
A plan is what a customer actually subscribes to. It bundles priced products into one package: a POS subscription fee, a per-transaction charge, and an email allowance sold together as Retail Suite.
Products and prices describe what things cost. A plan decides what is sold together, how much of each is included in the base price, and how much a buyer may take. A product can appear in as many plans as you like, at different allocations in each.
Plans are versioned
Versioning exists so that changing a plan is safe. You do not have to think about it in the normal case, and this section is mostly about why.
The default is automatic. Create a plan, add products, publish. Kontier keeps v1. Later you change a price or add a product, publish again, and Kontier keeps v2. New customers get v2.
What happens to the subscriptions you already sold is decided per subscription,
by its version_track_mode — and the default is not the cautious one.
Publishing DOES move subscriptions that track `latest`
A subscription created without an explicit version_track_mode gets latest,
paired with immediate_prorate. Publishing a new version sweeps every such
subscription on that plan onto it, and the strategy decides the money: with
immediate_prorate the difference is prorated onto the current period, so an edit
can produce a charge your customer did not ask for.
Send "version_track_mode": "pinned" when you create the subscription if you want
it to stay where it is. See Subscriptions.
Versioning is what makes that a choice rather than an accident: a pinned subscription keeps the exact prices it was sold, and the sweep never touches it.
What you actually do
Change what you like, then publish. Two states matter:
| State | What it means |
|---|---|
| Current | What checkout offers and new subscriptions get |
| Staged | Your edits, not yet on sale |
The dashboard shows the gap plainly. A product you have attached but not yet published is badged Not offered, with Stage and Publish actions in the header until the two agree.
So the one habit worth forming: after editing a plan, publish it. If something you added is not appearing in checkout, that is almost always why.
Moving existing subscribers
You usually do not, which is why nothing moves by itself. When you do:
GET /v1/plans/{id}/publish-impact is a dry run. It tells you how many active
subscriptions track the latest version and would move, and how many hold a
version pin and would not. POST /v1/plans/{id}/migrate-subscribers moves them
once you are happy.
Both are read-then-act, on purpose — they are how you move subscriptions that are
pinned, deliberately and after looking. Subscriptions that track latest do
not wait to be asked: publishing moves them as part of the publish itself.
What each product adds
Every product on a plan carries its own allocation settings. These four columns are where most of the modelling happens.
Included quantity
How much of this product is bundled into the base price before per-unit billing
starts. A plan that includes 10,000 emails sets included_quantity to 10000;
the customer is billed only for what they use beyond it.
Leave it empty and every unit is billed.
Default quantity
What a new subscription starts with when the caller does not say. For a seat product this is the number of seats a fresh subscription is created with.
It is a starting point, not a limit: Min and Max quantity bound what a buyer may actually pick.
Rollover
Whether unused included allowance carries into the next period instead of expiring. Off by default, which is what most plans want. When on, you can cap the accumulated balance and expire it after a set number of periods.
Version
Whether this membership follows the product's latest version automatically
(latest) or stays pinned to the version it was attached at (pinned). Pin it
when a price change on the product must not silently reach this plan.
Create it in the dashboard
-
Open the plans list
In the sidebar under Billing, click Plans.
-
Create the plan
Click Create Plan. Give it an internal Name, and a Public Description if buyers will see it in checkout or the portal.
A plan starts empty, as a draft -
Attach your products
On the plan's Products tab, click Add Product for each product the plan sells, and set its allocation settings as you go.
-
Publish it
Use Stage, then Publish. This is the step that puts your changes on sale; everything before it is a draft.
Create it with the API
Two calls: create the plan, then attach each product with its allocation.
There is no publish endpoint
Publishing is a PATCH carrying effective_at, not a call to /publish. Omit
effective_at and the change is immediate; supply one and the version is
scheduled for that moment. save_as_draft keeps editing without publishing.
This is not the same machinery as scheduled changes, despite both using the words release and cancel. See Versioning.
Dashboard and API names
| In the dashboard | In the API |
|---|---|
| Name | name, operator-facing |
| Public Description | public_description, shown in checkout and the portal |
| Included Quantity | included_quantity, a string |
| Default Quantity | default_quantity, an integer |
| Min / Max quantity | min_quantity / max_quantity |
| Rollover | rollover_enabled, with rollover_max and rollover_expiry_periods |
| Version column | product_track_mode: "latest" or "pinned" |
| Not offered badge | the product is in the working set but not the published version |
| Publish v2 | a scheduled plan version, then released |
Where plans go next
- Subscribe a customer. The subscription pins the plan version it was created on, which is why publishing does not disturb it.
- Check the blast radius before you republish.
publish-impactsplits active subscriptions into those that would migrate and those pinned. - Move subscribers deliberately with
POST /v1/plans/{id}/migrate-subscriberswhen they should move.
Next step
Continue to Customers, then Subscriptions, to put this plan to work.
Reference
| Topic | When you need it |
|---|---|
| Scheduled changes | How a plan version is staged, released or cancelled |
| Plan clauses | Contract text attached to a plan |
| Dunning | The retry policy a plan applies to failed payments |
| Plans API | Every field, plus publish-impact, copy and migrate-subscribers |