Versioning and migrating

The server API is versioned by date, like Stripe. Send the version you built against in the TYS-Version header:

TYS-Version: 2026-10-25

• No header = the latest version. Every response’s TYS-Version header says which version answered.
• An unknown version is 400 invalid_api_version.
• The SDKs pin a version for you: @tryyoursize/node and tryyoursize send the version they were released with, so upgrading the library is how you move to a new version.
• Additive changes (new endpoints, new optional fields, new event types, new enum values in answers) can ship in any version. Write code that ignores fields it does not know. Breaking changes ship only in a new dated version.

The latest version is 2026-10-25. See the changelog.

Webhooks

Webhook envelopes carry their own api_version (today "2026-10"). See Webhooks.

Browser and mobile SDKs

TryYourSize.js is versioned by its CDN path (https://js.tryyoursize.com/v1/tys.js) and npm semver: improvements reach /v1/ automatically, breaking changes ship as /v2/. The window protocol is versioned separately, so an older SDK keeps working with newer windows.

Migrating to a new version

1. Read the changelog for every version between yours and the target. Each entry lists what changed and what to do.
2. Try the new version per request, in test mode. Send TYS-Version: <new date> on a few calls (the SDKs take apiVersion / api_version on the client, and Node.js per call in RequestOptions). Responses tell you which version answered.
3. Upgrade the SDK. @tryyoursize/node and tryyoursize pin the version they were released with; a new release moves you to its version. Check TryYourSize.API_VERSION (Node.js) or tryyoursize.API_VERSION (Python).
4. Webhooks carry their own envelope api_version: read it, and ignore fields you do not know.
5. Go live once your test-mode traffic shows no errors in Studio → Developers → Logs.

SDK versions

SDK	Versioning	Upgrade
TryYourSize.js (CDN)	Major in the path, /v1/	Automatic within /v1/; change the path for /v2/
@tryyoursize/sdk, @tryyoursize/react	npm semver	npm install @tryyoursize/sdk@latest
@tryyoursize/node, tryyoursize (Python)	semver, each release pins one API version	Upgrade the package, run your tests in test mode
iOS, Android, React Native, Flutter	semver	Update the dependency; the window updates itself

Moving from another size tool

Keep your existing size chart as the fallback: mount the TryYourSize element next to it (or replace its link with the size guide), and remove the old tool once the A/B holdout shows the effect on size returns. Send orders and returns from the start so the comparison has data.