# Versioning and migrating

> Date-based API versions in the TYS-Version header, SDK versions, and how to move to a new version safely.

Source: https://docs.tryyoursize.com/guides/versioning/

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

```http
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`](https://docs.tryyoursize.com/api/errors.md#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](https://docs.tryyoursize.com/api/changelog.md).

## Webhooks

Webhook envelopes carry their own `api_version` (today `"2026-10"`). See [Webhooks](https://docs.tryyoursize.com/guides/webhooks.md).

## 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](https://docs.tryyoursize.com/api/changelog.md)** 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](https://docs.tryyoursize.com/products/size-guide.md)), and remove the old tool once the [A/B holdout](https://docs.tryyoursize.com/guides/ab-holdout.md) shows the effect on size returns. Send orders and returns from the start so the comparison has data.