Skip to content
Ask the docs

Find answers across the QairoPay docs.

Type a question and we'll synthesize an answer from the docs with citations back to the source pages.

Versioning

QairoPay uses dated API versions, like 2026-05-19. Each version is a frozen snapshot of the API contract. Once we publish a version, its behavior is stable forever.

Picking a version

There are three ways your requests get a version, in order of precedence:

  1. Per-request header — QairoPay-Version: 2026-05-19. Overrides everything else, useful for one-off testing.
  2. Pinned account version — the version selected in the dashboard. Set once, applies to all your traffic. This is what you should use in production.
  3. No version specified — requests pin to the version that was current when your tenant was created.
GET /v1/passes
Authorization: Bearer qp_sk_live_...
QairoPay-Version: 2026-05-19

The version that handled your request always echoes back in the QairoPay-Version response header.

What counts as a breaking change

We publish a new version when we ship a change that any of the following would break:

  • A field is removed or renamed.
  • A field’s type changes.
  • A previously optional field becomes required.
  • A response field that used to be present becomes absent in some cases.
  • An enum value is removed.
  • An error code is renamed or repurposed.
  • A previously-unauthenticated endpoint requires auth.
  • A previously-allowed request becomes rejected.

We do not version for:

  • New endpoints.
  • New optional request fields.
  • New response fields (clients should ignore unknown fields).
  • New enum values (clients should handle unknown values gracefully).
  • New error code values within an existing type.
  • Behind-the-scenes performance or infrastructure changes.

When we publish versions

Roughly one new version per quarter. Each version is announced via:

  • An entry in the Changelog.
  • An email to the contact on file.
  • A dashboard banner shown to admins for 30 days.

A version is supported for at least 24 months after a newer version ships. We publish end-of-life dates in the changelog at the time of deprecation. Calls to a deprecated version receive a Sunset response header with the EOL date.

Bumping safely

  1. Read the changelog entry for the new version. It enumerates every breaking change.
  2. Test in sandbox by setting QairoPay-Version: <new> per-request. Run your full test suite.
  3. Roll out by switching the pinned version in your sandbox tenant.
  4. Once stable, switch the pinned version in your live tenant. There is no downtime — versions are negotiated per-request.

If you need to roll back, switch the pin back. Already-completed requests are unaffected.

SDK versioning

The TypeScript SDK ships a defaultApiVersion per major SDK release. Pin your tenant’s account version to that for the smoothest experience. Override per-call with { apiVersion: "..." } when you want a different one.