Skip to main content
Commet uses date-based API versioning inspired by Stripe. Every breaking change is gated behind a version, and your integration stays on its pinned version until you explicitly upgrade.

​
Version format

Versions use the date they were released: YYYY-MM-DD (e.g. 2026-05-01). The current version is 2026-08-27.

​
How versions are resolved

Every API request and webhook delivery resolves a version using this priority: For API requests, send the Commet-Version header to override your organization pin for that request:
For webhooks, each endpoint can have its own pinned version. If not set, it falls back to your organization’s pin.

​
What changes between versions

A new version ships whenever a breaking change needs one — sometimes several land in the same month, sometimes months pass without any. This never affects a running integration: your organization and webhook endpoints stay on their pinned version regardless of how many versions ship after it. A breaking change is anything that:
  • Removes a field from a response
  • Renames a field
  • Changes a field’s type
  • Changes the structure of a nested object
  • Alters default behavior
Non-breaking changes ship continuously and never require a version bump:
  • New fields added to responses
  • New event types. An endpoint receives only the events it lists, so a new type reaches an endpoint only after you add it
  • New API endpoints
  • New optional request parameters
  • New values in existing enums, such as a new billing interval. Your integration should accept values it does not recognize instead of failing

​
Plan edits publish plan versions

Editing a plan’s prices, features or credit and balance rules through the API, MCP or CLI publishes a new version of the plan. New buyers get the new version; existing subscriptions keep the version they are on until you move them with Change subscription version or Move subscribers to a plan version. Before plan versions, some of these edits also changed existing subscriptions, at once or at their renewal. This is a change in product behavior, not in the shape of requests or responses. Unlike the breaking changes listed above, it did not ship behind a new API version: it applies to every API version, including pinned ones.

​
Backward compatibility policy

When a new version is released:
  1. Your existing pin continues to work unchanged — responses keep the shape of your pinned version
  2. Pins never expire: there is no support window and no automatic upgrade. Your version changes only when you change it
  3. If a pin references a version that no longer exists, requests on it resolve to the current version
  4. The legacy unversioned /api/* paths (predating /api/v1) return Deprecation: true and Sunset headers with a Link to their /api/v1 successor — versioned endpoints never carry these headers

​
Upgrading your version

  1. Review the changelog for breaking changes between your current and target version
  2. Update your code to handle the new response shapes
  3. Test with the Commet-Version header before committing
  4. Change your organization’s pinned version from the dashboard
For webhooks, you can pin a new endpoint to the latest version while keeping the old one active. Both receive events transformed to their respective versions, letting you validate in production before switching.

​
SDK behavior

Each SDK release ships pinned to the API version it was built against and sends the Commet-Version header automatically. This prevents the class of bug where upgrading an SDK version silently changes response shapes. Every SDK also lets you pin a different version at client construction — no SDK upgrade required:

​
Webhook versioning

Webhook payloads include an apiVersion field in the envelope so you always know which version shaped the data:
Each webhook endpoint can be pinned independently. When migrating, create a second endpoint pinned to the new version — both receive every event they list, each transformed to its own version. Once the new endpoint is working, delete the old one.