The shopper's recommended size for up to 25 products
const url = 'https://api.tryyoursize.com/v1/recommendations';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"handle":"example","products":["example"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.tryyoursize.com/v1/recommendations \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "handle": "example", "products": [ "example" ] }'Key scopes: fit_checks:read. A secret key (sk_) has every scope; a restricted key (rk_) needs the scopes listed.
From the brand’s server (or a headless storefront’s backend) with a secret key, or a restricted key with fit_checks:read. Send the handle the browser SDK gave your page (tys.recommendationHandle()); the answer has sizes only, in your size labels, never measurements. Like a page view, it never starts a simulation: a body already simulated with the garment answers with the existing result, or with a size estimate when one is certain for this body; otherwise the status is unavailable until the shopper asks for the try-on. A delivered size counts as a fit check, like in the browser. The handle’s mode must match the key’s (a test handle with a live key is 403). A handle whose shopper deleted their account or disconnected the store is refused (401 handle_invalid).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”A unique value per logical request (a UUID v4 is ideal), 1-255 printable ASCII characters. With a secret or restricted key, the first response is stored for 24 hours per store and mode: a retry with the same key and the same body gets the stored response back (header Idempotent-Replayed: true); the same key with a different body is 422 idempotency_key_reused; a retry while the first request still runs is 409 idempotency_key_in_use. Responses with a 5xx status are not stored, so a retry runs again.
Request Bodyrequired
Section titled “Request Bodyrequired”object
A recommendation handle from the browser SDK (tys.recommendationHandle()).
Product SKUs / style IDs (what you pass to the element as product).
Example generated
{ "handle": "example", "products": [ "example" ]}Responses
Section titled “Responses”One answer per product, in the order asked
object
The shopper’s size for one product: sizes only, never measurements. Same statuses as the browser SDK’s recommendation event, minus signed_out (a handle always belongs to a signed-in shopper).
object
ready: a size. computing: a simulation the shopper started is running (ask again later). none: simulated, no size can be worn. unavailable: no published garment for this product, not simulated on this body yet, or the store’s plan has no fit checks left. A page view or this API never starts a simulation.
The recommended size in the store’s label (the product’s size map), or null.
The same size as entered in TryYourSize Studio, or null.
Sizes that can be worn on this body, in the store’s labels.
How the size was determined: estimate (a size estimate certain for this body, no try-on of it yet) or simulated (from a try-on of this body). A coarse informational label: do not build logic on its values.
The try-on that produced the size, when there is one. Send it back with orders for attribution.
Example
{ "data": [ { "status": "ready", "method": "estimate" } ], "mode": "test"}Invalid request
Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.
object
Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.
Example
{ "code": "not_found", "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"}Missing or invalid credentials
Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.
object
Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.
Example
{ "code": "not_found", "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"}Not allowed
Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.
object
Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.
Example
{ "code": "not_found", "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"}Too many requests; retry later
Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.
object
Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.
Example
{ "code": "not_found", "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"}Was this page helpful?
Thank you. We read every answer.