API versions

The Backstage API uses dated versions - each version is named after the day it was released, for example 2026-10-02. The current version is 2026-10-02.

Within a version the API only ever changes additively: new endpoints, new optional parameters and new response fields may appear, but existing behaviour never changes. Breaking changes are only ever introduced in a new dated version, so an integration pinned to a version keeps working unchanged.

How versioning works#

• Pin with the TL-Version header. Send the version date on every request to pin the API behaviour your integration expects. Responses echo the version that served the request in a TL-Version response header.
• Organisations are pinned at signup. When an organisation is created it is pinned to the then-current version. Requests that omit TL-Version use the organisation's pinned version, so existing integrations are never broken by a new release.
• SDK majors pin a version. Each major release of an official SDK hardcodes the version it speaks (the current TypeScript SDK sends 2026-10-02). Upgrading the SDK is how most integrations move between API versions.
• Additive changes only within a version. We may add endpoints, optional request fields and response fields at any time without releasing a new version. Your integration should ignore response fields it does not recognise.
• Twelve-month deprecation windows. When a version is deprecated you have at least 12 months before it is sunset. While deprecated, responses include Deprecation and Sunset headers telling you when the version stops being served.

Pinning a version#

curl https://api.ticketlayer.com/v1/events \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "TL-Version: 2026-10-02"

Discovering versions at runtime#

The full version list, including deprecation and sunset dates, is available from the API itself:

curl https://api.ticketlayer.com/v1/meta/versions

Version status#

Version history#

2026-10-02#

The checkout loop (TKT-575): checkout answers a checkout object saying what happens next, and reads TL-Client-Capabilities. Also the payments programme (P-TKT-46), additive: payment shares held by more than one party, the payment method catalogue and per-channel method policies, payments staff record and split tender, orders awaiting payment with due dates and send-before-payment, cash sessions, processing costs chosen by the connection owner, fee components, surcharges and all-in headline prices, the cart as a quote, tax registrations, tax lines and tax documents, Adyen and PayPal in merchant-credentials mode, pass identifiers, holders, transfers and signed barcodes, delivery methods and fulfilment, security policies and wallet passes, holder slots, add-ons and packages, stored value, account credit and gift cards. New operations, optional request fields, new response fields, new enum values that appear only once an organisation uses the feature that makes them (an order awaiting payment, a gift card line), and new webhook event types (payment.recorded, cash_session.closed). Nothing a 2026-06-13 caller sends or reads changes meaning, so there are no transforms and 2026-06-13 callers are served the additions too.

Breaking changes#

• POST /carts/{cartId}/checkout (Live) and POST /cart/{cartId}/checkout (staff) answer a checkout object: status (requires_input, requires_approval, requires_payment, processing, complete), nextAction, capabilitiesApplied, deferred and expiresAt. Earlier versions do not receive it.
• order in the checkout answer is null while checkout.status is requires_input: a requirement must be answered before the order is made. On earlier versions every requirement takes its fallback, so the order is always made or the checkout refused.
• TL-Client-Capabilities is read at checkout: the API asks the client inline for what it declared, sends a redirect to the hosted completion page for what it did not when it declared redirect, and applies the requirement's fallback otherwise. Earlier versions ignore the header.
• Checking out a cart that is already checked out answers the checkout as it stands (requires_approval, requires_payment, processing or complete) instead of 409 CART_NOT_ACTIVE, so the call is safe to repeat; an expired or cancelled order answers 409 CHECKOUT_CLOSED.

Migrating#

Review each change above and update your integration to handle the new behaviour, then update the TL-Version header (or upgrade to an SDK release that targets 2026-10-02 or later). Until you do, your requests continue to behave exactly as they did on your pinned version.

2026-06-13#

Baseline dated version - all prior behaviour, no transforms.

No breaking changes - this is the baseline dated version.

See also#

• API changelog - additive changes and fixes within versions
• Backstage API introduction