Skip to main content

​
API versioning & deprecation

Orbit’s REST API is versioned by date (e.g. 2026-03-01). Every response carries the version it was served as in the X-API-Version header, so an integration can always tell which version answered.

​
Pinning a version

Send the X-Api-Version (or Api-Version) request header to pin a dated version per request — the same model as Stripe’s Stripe-Version header. No request header means the current version; there is no account-level pin to configure, so you can flip a pin at any time by changing a header. If you pin a version that is not in the registry — a typo or a stale pin — the request succeeds and is served by the current version. The response adds an X-Api-Version-Warning header naming the pin it did not recognize, instead of failing with a 4xx from a response hook.

​
Lifecycle

Each dated version moves through three stages: Deprecated versions keep working until their sunset date; only after that date do pinned requests fall through to the current version. This window — at least six months — is the migration runway. A new dated version is cut only for breaking changes. Additive, backward- compatible changes (new endpoints, new optional fields, new enum values) land on the current version without a new date.

​
Discovering the registry

GET /developer/api-versions lists every dated version with its status, released date, deprecation date, and sunset date, plus the migration_url linking back to this page. Integrations that need to schedule migrations should poll this endpoint rather than hard-coding dates.

​
Deprecation headers

When your request resolves to a deprecated or sunset version, the response adds standard Deprecation and Sunset headers (RFC 8594) plus a Link: <…>; rel="deprecation" header pointing here, and an X-Api-Deprecation-Info header naming the sunset date and the version to migrate to. Client SDKs surface the same information as a non-fatal warning.

​
Response example