API Versioning

The Genius Checkout API is versioned in the URL prefix. Today's version is /v1.

https://app.geniuscheckout.com/api/v1/checkout-sessions

A future breaking change ships as /v2 alongside /v1 — the old version keeps running while consumers migrate.

Stability within a major version

Within a major version (/v1) we never make breaking changes. We may:

• Add new endpoints.
• Add new optional fields to request bodies.
• Add new fields to response bodies.
• Add new event types or new fields on existing webhook payloads.
• Add new currencies to the supported list.
• Add new statuses to existing enums (but only when contextually safe — see below).

We do not, within /v1:

• Remove or rename fields.
• Change a field's type.
• Make an optional field required.
• Change an HTTP status code's meaning.
• Change the HMAC signature scheme.

Treat unknown fields as forward-compatible. Don't strictly validate the shape of responses — log + ignore anything you don't recognize.

Webhook event types

We may introduce new event types into the standard catalog (e.g., a new subscription.dunning_started). Subscribers should ignore unrecognized event types rather than 4xx them.

Status enums

When we add a new status (e.g., a new TransactionStatus), we treat it as additive — your code should handle the new value as if it were a related existing status (e.g., a new failure status should be treated like failed). To make this easy, the Webhooks and resource pages note the complete current enum set, and the changelog records every addition.

Deprecation policy

Removing an endpoint or making a breaking change within a major version is reserved for the rare case where we cannot maintain it safely (a vulnerability, a vendor end-of-life, a compliance directive). When we do:

1. 12-month deprecation notice posted to the Changelog, emailed to every API consumer with traffic to the affected endpoint in the previous 30 days, and announced on the dashboard.
2. Sunset header on every response from the deprecated endpoint, with the planned removal date in HTTP-date format. This follows RFC 8594.
3. Deprecation header set to true on every response.
4. Link header pointing at the replacement endpoint and its documentation.

HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 22 May 2027 00:00:00 GMT
Link: <https://docs.geniuscheckout.com/en/payments>; rel="successor-version"

You have a year from the first Sunset header to migrate. The endpoint stops responding on that date; existing requests start receiving 410 Gone.

Major-version bumps

When a /v2 ships:

• /v1 keeps running with the deprecation headers above.
• The migration window is at least 18 months before /v1 is taken offline.
• A migration guide ships on the docs site at /migration/v1-to-v2.

How to discover what's changed

• Watch the Changelog — every shipped change with the date.
• Subscribe to release announcements by emailing [email protected] and asking to be added to the developer newsletter.
• Run a periodic sanity-check against your integration's smoke-test suite — we publish test cards you can wire into CI.

Next

• Changelog — what shipped, when
• Webhooks — event additions are version-safe