API Versioning

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-05-01.

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:

curl https://commet.co/api/v1/subscriptions \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "Commet-Version: 2026-05-01"

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

Breaking changes are batched into versions released twice per year. 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
• New API endpoints
• New optional request parameters

Backward compatibility policy

When a new version is released:

1. Your existing pin continues to work unchanged
2. The previous version is supported for 12 months after the new version ships
3. Deprecated versions return Deprecation: true and Sunset headers with the end date
4. After the sunset date, requests on that version are automatically upgraded

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

SDKs pin to the version they were built against:

All SDKs send the Commet-Version header automatically. This prevents the class of bug where upgrading an SDK version silently changes response shapes.

Webhook versioning

Webhook payloads include an apiVersion field in the envelope so you always know which version shaped the data:

{
  "event": "subscription.activated",
  "timestamp": "2026-05-12T14:30:00.000Z",
  "organizationId": "org_abc123",
  "mode": "live",
  "apiVersion": "2026-05-01",
  "data": { ... }
}

Each webhook endpoint can be pinned independently. When migrating, create a second endpoint pinned to the new version — both receive every event, each transformed to its own version. Once the new endpoint is working, delete the old one.