Versioning

Five things in Kontier carry versions: plans, products, tax rules, rate tables and price formulas. They share one model: you edit a working draft, then publish it as a new version, now or at a set time.

Versioning exists so that editing something you already sell is safe. Change a price, publish, and only the subscription lines that follow the catalog move, at the moment their version-change rule says. Lines that are pinned keep what they were sold.

You mostly do not have to think about it. Edit, publish, done. This page is for when you do.

What is not versioned

Prices, meters and costs have no versions of their own, and neither do customers, subscriptions or invoices.

A price belongs to a product: editing one lands in the product's working draft and reaches billing when the product is next published. An invoice is immutable once finalised. A subscription records its own history as revisions (see Subscriptions), and each of its lines names the catalog version it was drawn from.

Promotions have a lifecycle of their own (draft, live, ended) and go live with POST /v1/promotions/{id}/publish, not through the model on this page.

The working draft

Edits to what an entity bills stage on its working draft and change nothing that is live:

Display-only fields (names, descriptions, metadata) land live immediately. POST …/draft (for example POST /v1/plans/{id}/draft) opens the draft explicitly, on the live head or on one of the entity's scheduled versions (base_version_id).

None of the update routes publishes. On plans and products, sending "status": "active" is refused with PUBLISH_IS_A_CHANGE; there is no effective_at, save_as_draft or publish_now field anywhere.

Publishing is a change

Taking a draft live is POST /v1/changes with the operation catalog.publish_version. subject_kind names the entity: plan, product, rate_table, tax_rule or price_formula.

Publish a product's draft at 09:00 Berlin time
curl -X POST https://api.kontier.eu/v1/changes \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "operation":    "catalog.publish_version",
    "subject_kind": "product",
    "subject_id":   "3f2a8c1e-5b7d-4e9a-9c1f-2d6b8e4a7c10",
    "when":         "at",
    "at":           "2027-03-01T09:00:00Z",
    "zone":         "Europe/Berlin",
    "payload":      { "release_name": "March list prices" }
  }'

payload is optional naming: release_name (up to 120 characters) and release_note (up to 2,000). You can set or change both later with PATCH …/versions/{version} on the entity (for example PATCH /v1/products/{id}/versions/{version}), which never creates a version.

Add "gate": "approval" to hold the publish until a second person releases it. A person decides approvals in the dashboard. The API can read them (GET /v1/approvals, GET /v1/approvals/{id}) but not decide them.

Scheduled versions

A scheduled publish freezes the draft into a pending version, and the working draft is free again for the next edit. The entity lists pending releases under scheduled_versions, in the order they will publish, each with:

The entity's own state never says "scheduled": lifecycle is draft, published or archived, and an entity with a pending release is still what it was, and still editable.

Cancelling cancels the release, not the edit: the content goes back to being staged and can be published later, or discarded with the entity's DELETE …/draft. Once a change has run or been retired, both PATCH and DELETE answer 409 CHANGE_NOT_EDITABLE. See Scheduling for the full change lifecycle.

Version rows

GET …/versions and GET …/timeline on each entity (for example GET /v1/rate-tables/{id}/timeline) return version rows. The timeline lists them in the order they fired and will fire; pass include=all for the working draft and archived rows too.

✕

Each row also says who made it in origin: manual (an operator or API key published it), scheduled_release (a scheduled publish fired) or cascade (republished automatically because something it depends on published, such as a plan that tracks a product's latest version).

History

GET /v1/plans/{id}/history and GET /v1/products/{id}/history list the published and scheduled versions newest first, each with its publisher, release name, effective time and a readable diff against the version it replaced. On every kind, GET …/versions/{version}/diff compares versions directly.

Before you publish

{version} is a version number; followers and diff also accept the word draft, to ask about the open working draft. Plans and products also have an entity-level GET /v1/plans/{id}/publish-impact and GET /v1/products/{id}/publish-impact; plans add GET /v1/plans/{id}/publish-preflight, which runs the real publish and rolls it back to tell you whether it would succeed.

Who follows a new version

Nothing is migrated in bulk, and there is no migrate call. Each consumer either follows the newest version or holds still:

• A subscription line has a track: follow or pinned. A following line moves when its plan or product publishes, at the time its version_change says: immediate_prorate, next_period or at_phase_change. A pinned line keeps its version. A line that states neither inherits them from the plan version and the subscription's defaults; see Plans.
• A plan membership chooses per product with product_track_mode: latest (publishing the product republishes the plan) or pinned.
• A price tier that uses a formula records the formula version in force when the product publishes (formula_version_id). A pinned line bills that exact formula version; a following line uses the formula's current head.

What each entity can do

Where versioning shows up