Skip to main content

Versioning

The Customer API uses calendar-based API profiles — a string in the form YYYY-MM, for example 2026-04. The current profile is exposed via the /api/version endpoint and inside every schema response.

What's in a profile?​

An API profile defines:

  • The set of endpoints available.
  • The fields included in each response.
  • The behaviour of any endpoint-level rules (such as which products are included in /products for a given customer).

When Kiss adds new endpoints or new fields without breaking existing clients, the profile does not change. Your client continues to work with no action required.

When Kiss makes a breaking change — for example, removing a field or changing the semantics of a value — the profile name changes.

What counts as a breaking change?​

Breaking changes include:

  • Removing an endpoint.
  • Removing a field from a response payload.
  • Changing the data type of a field.
  • Changing what a field represents (for example, switching PriceExclVAT from a discounted to a non-discounted figure).

Non-breaking changes include:

  • Adding a new endpoint.
  • Adding a new field to an existing response.
  • Adding a new value to an enumeration.

When in doubt, the schema endpoints (/products/schema, /stock/schema) describe the live payload shape — your client can compare them against an internal cached copy on startup and alert you if the surface changes.

How to check the current profile​

GET /api/version (no authentication required) returns:

{ "apiVersion": "2026-04" }

This is the profile the deployment is currently serving. Cache it and verify it on every run — when the value changes, review the release notes.

What versions look like in the URL​

The current URL design does not include the profile in the path — endpoints are unversioned (e.g. /products, not /v1/products or /2026-04/products). The profile is signalled by the response from /api/version and inside schema responses.

This is a deliberate choice that keeps your client code simple — when Kiss deploys a new profile, you usually don't need to change your URLs.

How upgrades work in practice​

When Kiss releases a new profile:

  1. The new profile is announced ahead of time, with release notes describing the changes.
  2. The old profile remains live in parallel for a transition window so that customers can migrate at their own pace.
  3. When the transition window ends, the old profile is retired and /api/version returns the new profile.

For non-breaking changes (most of them), no migration is required.

Recommendations for your client​

  • Cache the current profile in your client. Compare it against /api/version on each run and log a warning if it has changed unexpectedly.
  • Pin your tests to a known profile so that you can detect when a schema you depend on has changed.
  • Use the schema endpoints if your application needs to be resilient to new fields without code changes.

Reporting compatibility issues​

If a new profile breaks your integration in a way that isn't documented in the release notes, please open a support ticket with a sample request and response so we can investigate.