# TryYourSize API

Source: https://docs.tryyoursize.com/api/reference/

Server API conventions: authenticate with `Authorization: Bearer sk_…` (or a restricted `rk_…` key holding the operation's key scopes). Pin the version with the `TYS-Version` header (a date, e.g. `2026-10-25`; without it the latest version answers and the response's `TYS-Version` says which). Errors are `{error, status, code, doc_url, request_id}`. POSTs accept an `Idempotency-Key` (responses stored 24 h). Lists are cursor-paginated (`limit`, `cursor` → `data`, `has_more`, `next_cursor`). Rate limits answer `429` with `Retry-After`; every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.

Base URL: `https://api.tryyoursize.com`. Version header: `TYS-Version`. Spec: https://docs.tryyoursize.com/openapi.json

## Authentication

- **PublishableKey**: The store's publishable key (pk_test_… / pk_live_…). Safe in browsers; works only from the origins registered for the key.
- **SecretKey**: A secret key (sk_test_… / sk_live_…) or a restricted key (rk_test_… / rk_live_…) from your server: `Authorization: Bearer sk_…`. A secret key has every scope; a restricted key only the scopes it was created with. Each operation lists its key scopes.

## Embed

Called by TryYourSize.js and the measuring window from your page (publishable key). You do not call these yourself; they are listed so you can read your request logs and CSP reports.

- [Bootstrap the measurement window](https://docs.tryyoursize.com/api/reference/operations/initembed.md): `POST /v1/embed/init`
- [Count a shopper funnel step (measuring window)](https://docs.tryyoursize.com/api/reference/operations/recordfunnelevent.md): `POST /v1/funnel_events`

## TryOn

The try-on window's routes (publishable key, from our window's origin). Shown for reference.

- [Is "See it on you" available for a product?](https://docs.tryyoursize.com/api/reference/operations/getproducttryon.md): `GET /v1/products/{product}/tryon`
- [See a product on the shopper's body](https://docs.tryyoursize.com/api/reference/operations/starttryon.md): `POST /v1/tryon`
- [A try-on's status, progress and result](https://docs.tryyoursize.com/api/reference/operations/gettryon.md): `GET /v1/tryon/{tryon_id}`
- [The colourways the window draws on the simulated garment](https://docs.tryyoursize.com/api/reference/operations/getpublicproductappearance.md): `GET /v1/products/{product}/appearance`

## Audit

Your organization's audit log, read with a restricted key holding `audit:read`.

- [Audit log of the key's organization (server API)](https://docs.tryyoursize.com/api/reference/operations/listauditeventswithkey.md): `GET /v1/audit_events`

## Outcomes

Orders and returns from your server, for the A/B results and size-related return rates. No customer data is accepted.

- [Record an order (idempotent by order ID)](https://docs.tryyoursize.com/api/reference/operations/createoutcomeorder.md): `POST /v1/orders`
- [Record a return of an order line (idempotent by return ID and line)](https://docs.tryyoursize.com/api/reference/operations/createoutcomereturn.md): `POST /v1/returns`

## Recommendations

The shopper's recommended size for your server or a headless storefront, from a handle the browser SDK issues. Sizes only, never measurements.

- [Seal the signed-in shopper's body into a handle for the brand's server](https://docs.tryyoursize.com/api/reference/operations/createrecommendationhandle.md): `POST /v1/recommendation_handles`
- [The shopper's recommended size for up to 25 products](https://docs.tryyoursize.com/api/reference/operations/createrecommendations.md): `POST /v1/recommendations`

## Catalog API

Products, size maps, fit groups and garment drafts, with a secret key or a restricted key holding the listed scopes. The catalog is shared by test and live mode: test answers drafts, live answers published versions.

- [List the store's products](https://docs.tryyoursize.com/api/reference/operations/listcatalogproducts.md): `GET /v1/products`
- [Create a product](https://docs.tryyoursize.com/api/reference/operations/createcatalogproduct.md): `POST /v1/products`
- [A product](https://docs.tryyoursize.com/api/reference/operations/getcatalogproduct.md): `GET /v1/products/{product}`
- [Update a product](https://docs.tryyoursize.com/api/reference/operations/updatecatalogproduct.md): `PATCH /v1/products/{product}`
- [A product's size map (Studio size → your size label)](https://docs.tryyoursize.com/api/reference/operations/getcatalogsizemap.md): `GET /v1/products/{product}/size_map`
- [Replace a product's size map](https://docs.tryyoursize.com/api/reference/operations/savecatalogsizemap.md): `PUT /v1/products/{product}/size_map`
- [Garment versions of a product, newest first](https://docs.tryyoursize.com/api/reference/operations/listcataloggarments.md): `GET /v1/products/{product}/garments`
- [Start a new draft garment version](https://docs.tryyoursize.com/api/reference/operations/createcataloggarmentdraft.md): `POST /v1/products/{product}/garments`
- [A garment version](https://docs.tryyoursize.com/api/reference/operations/getcataloggarment.md): `GET /v1/garments/{garment_id}`
- [Replace a draft's content](https://docs.tryyoursize.com/api/reference/operations/updatecataloggarmentdraft.md): `PUT /v1/garments/{garment_id}`
- [Publish a complete draft](https://docs.tryyoursize.com/api/reference/operations/publishcataloggarment.md): `POST /v1/garments/{garment_id}/publish`
- [List fit groups](https://docs.tryyoursize.com/api/reference/operations/listcatalogfitgroups.md): `GET /v1/fit_groups`
- [Create a fit group](https://docs.tryyoursize.com/api/reference/operations/createcatalogfitgroup.md): `POST /v1/fit_groups`
- [A fit group](https://docs.tryyoursize.com/api/reference/operations/getcatalogfitgroup.md): `GET /v1/fit_groups/{fit_group_id}`
- [Move products into a fit group](https://docs.tryyoursize.com/api/reference/operations/linkcatalogfitgroupproducts.md): `POST /v1/fit_groups/{fit_group_id}/products`