Versioning and deprecation

How Store API versions are supported, deprecated with at least 12 months' notice, and retired.

Tringify names each version of its public APIs by calendar month. A version fixes the requests, responses, and webhook payloads your integration relies on, so later platform changes do not break it. This page explains how long a version stays available, how you are told that it is going away, and what happens when it does.

Current versions#

API	Version	How requests choose it	Status
Store API	`2025-01`	Each token is pinned to a version when it is created. Send requests to `https://api-store.tringify.com/api/2025-01`. Successful responses include `X-Tringify-API-Version`.	Supported. Not deprecated, no sunset date.

A Store Admin token is pinned when it is created. An app token uses the version declared by the app release the store installed.

Lifecycle#

Status	What it means
Supported	Fully available. New apps and tokens can use it. A version stays supported until it is deprecated.
Deprecated	Still served, so existing integrations keep working, but new apps and tokens can no longer choose it. Every response carries the `Deprecation`, `Sunset`, and `Link` headers described below. Upgrade before its sunset date.
Sunset	No longer served. A request with a token pinned to it fails with `403 API_VERSION_UNSUPPORTED`.

Deprecation policy#

A version is deprecated only when a newer version is available to move to.
A deprecated version keeps working for at least 12 months. Its sunset date is never less than 12 months after its deprecation date.
From the day a version is deprecated, its deprecation and sunset dates are listed on this page and sent in response headers.
From 00:00 UTC on the sunset date, the version is no longer served and requests for it are refused.

Deprecation headers#

Every response for a deprecated version carries three headers, including error responses. They describe the version your token is pinned to. Supported versions send none of these headers.

Header	Value	Standard
`Deprecation`	`@` followed by the deprecation date as Unix seconds (00:00 UTC on that date).	RFC 9745
`Sunset`	The sunset date as an HTTP date. The version stops being served at this moment.	RFC 8594
`Link`	This page's URL with `rel="deprecation"`.	RFC 9745

For example, if the Store API version 2025-01 were deprecated on 1 January 2027 with a sunset date of 1 January 2028, a response would include these headers. The dates are an example only; no version is deprecated today.

http

HTTP/1.1 200 OK
Content-Type: application/json
X-Tringify-API-Version: 2025-01
Deprecation: @1798761600
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: <https://dev-docs.tringify.com/store-api/getting-started/versioning>; rel="deprecation"; type="text/html"

Browser clients can read the headers: the Store API lists Deprecation, Sunset, and Link in Access-Control-Expose-Headers.

Detect a deprecated version#

Check responses your integration already receives for a Deprecation header, and alert your team when it appears. Record the Sunset date and upgrade before it. To check by hand, print the response headers of any request.

check-store-api.sh bash

curl -s -D - -o /dev/null "https://api-store.tringify.com/api/2025-01/discover" \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  | grep -iE '^(x-tringify-api-version|deprecation|sunset|link):'

In code, read the headers from each response. This function works with fetch responses from either API.

deprecation.js javascript

export function readDeprecation(response) {
  const deprecation = response.headers.get("Deprecation");
  if (!deprecation) return null; // the version is supported
  const sunset = response.headers.get("Sunset");
  return {
    deprecatedAt: new Date(Number(deprecation.slice(1)) * 1000),
    sunsetAt: sunset ? new Date(sunset) : null,
    docs: response.headers.get("Link"),
  };
}

const response = await fetch("https://api-store.tringify.com/api/2025-01/discover", {
  headers: { Authorization: `Bearer ${process.env.TRINGIFY_TOKEN}` },
});
const notice = readDeprecation(response);
if (notice) {
  console.warn(`API version deprecated on ${notice.deprecatedAt.toISOString()}, sunset ${notice.sunsetAt?.toISOString()}`);
}

Upgrade to a newer version#

Store Admin tokens: create a new token in Store Admin under Settings > API Tokens, which is pinned to the current version, and replace the old one.
Apps: publish an app release that declares the newer version. An app token uses the version of the release the store has installed.
Test your integration against the newer version before switching, and confirm the X-Tringify-API-Version response header names the version you expect.

See Authentication for the API_VERSION_UNSUPPORTED error.