Skip to main content
The Partner API is versioned by date. A breaking change ships as a new dated version, and the version you integrated against keeps working unchanged.

​
Picking a version

Every request resolves to exactly one version, in this order:
  1. The Clemta-Version header, if you send one.
  2. Your account default, if you have set one in the dashboard.
  3. The latest version, if neither of the above applies.
Send the header to pin a request explicitly:
The effective version is echoed back on every response in the same header, so you can always confirm which contract answered you.

​
What a version pins

A dated version pins the request and response shapes and the set of error codes. When a new version renames or restructures a field, the old version still answers with the old shape. Your integration does not have to move until you choose to. An unknown version is rejected with invalid_api_version. Use a date the API versions page lists, or omit the header to run on your account default.

​
Deprecation and sunset

A version can be deprecated once a newer one supersedes it. It keeps answering until a published sunset date, but every response on it carries two headers:
  • Deprecation marks the version as deprecated.
  • Sunset is the date after which it may stop answering.
You can detect this from traffic alone, without polling the docs. The API versions page lists any deprecation schedule. Move to the current version before the sunset date to avoid disruption.

​
Webhooks are versioned too

The events we deliver to your endpoint are versioned the same way. Each delivery is rendered at the webhook version set for your workspace, so a payload keeps its shape even as newer API versions restructure the same resource. The event’s data.object therefore matches the version you integrated against, not necessarily the latest one. Set your webhook version in the dashboard. Until you set one, deliveries render at the latest version.

​
Downloading the spec

Every version’s full OpenAPI description is served for download, so you can generate a client or diff two versions. See OpenAPI specs for the version-resolving and frozen dated URLs.
Last modified on October 2, 2026