Start a new draft garment version
const url = 'https://api.tryyoursize.com/v1/products/example/garments';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"category":"tshirt","fit_intent":"skinny","sizes":["example"],"poms":{"additionalProperty":{"additionalProperty":1}},"grading":{"base_size":"example","increments_mm":{"additionalProperty":[1]}},"fabric":{"name":"example","construction":"jersey","composition":[{"fiber":"cotton","pct":1}],"weight_gsm":1,"stretch_warp_pct":1,"stretch_weft_pct":1,"notes":"example"},"import_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","season":"example","tolerances_mm":{"additionalProperty":1},"spec_source":{"kind":"manual","filename":"example"},"footwear":{"shoe_type":"sneaker","size_system":"eu","basis":"foot_length","rows":[{"labels":{"additionalProperty":"example"},"length_mm":1,"fitting":"example","width_mm":1,"girth_mm":1}]},"elastic_waist":true,"elastic_waist_inferred":false,"rise_type":"low","rise_type_inferred":false,"worn_at_mm":1}'};
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/products/example/garments \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "category": "tshirt", "fit_intent": "skinny", "sizes": [ "example" ], "poms": { "additionalProperty": { "additionalProperty": 1 } }, "grading": { "base_size": "example", "increments_mm": { "additionalProperty": [ 1 ] } }, "fabric": { "name": "example", "construction": "jersey", "composition": [ { "fiber": "cotton", "pct": 1 } ], "weight_gsm": 1, "stretch_warp_pct": 1, "stretch_weft_pct": 1, "notes": "example" }, "import_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "season": "example", "tolerances_mm": { "additionalProperty": 1 }, "spec_source": { "kind": "manual", "filename": "example" }, "footwear": { "shoe_type": "sneaker", "size_system": "eu", "basis": "foot_length", "rows": [ { "labels": { "additionalProperty": "example" }, "length_mm": 1, "fitting": "example", "width_mm": 1, "girth_mm": 1 } ] }, "elastic_waist": true, "elastic_waist_inferred": false, "rise_type": "low", "rise_type_inferred": false, "worn_at_mm": 1 }'Key scopes: garments:write. A secret key (sk_) has every scope; a restricted key (rk_) needs the scopes listed.
Sizes, points of measure (mm) per size, grading and fabric, as in Studio. A product has at most one draft (409). Send an Idempotency-Key to retry safely.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The product: its TryYourSize ID (UUID) or the brand’s SKU / style ID (external_id). An ID is looked up first.
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
The garment type; it sets which POMs are needed (footwear has a size chart instead).
The designer’s intended silhouette; sets the ease targets the fit judgement compares against.
Size labels, smallest to largest.
Garment measurements per size: size label → POM code → millimetres. Widths are flat half-measurements. See GET /v1/studio/garment_dictionary for codes and plausible ranges.
object
object
How the POM table was derived: the base size’s values plus, per POM, the increment (mm) between each pair of consecutive sizes (len = number of sizes - 1). The table stays the source of truth.
object
object
What the tech pack / mill sheet says.
object
object
Areal density, g/m².
Stretch along the warp (lengthwise), percent.
Stretch along the weft (crosswise), percent.
Pattern import linked to this version (omit to unlink).
Season tag, e.g. “SS27”.
Spec-sheet tolerance per POM code, ± mm (e.g. {“chest_width”: 10}). Optional; the flat preview uses ±5 mm when a POM has none.
object
Where the POM table came from, kept for audit. Set by Studio’s paste/import.
object
A footwear version’s size chart (category footwear). The version’s sizes must be the chart’s labels in the chart’s size_system, in row order (fittings collapsed). Footwear has no POMs and no 3D fit check.
object
Sets the room left in front of the toes that a size is chosen for.
A shoe size system: eu (Paris points), uk, us_men, us_women, or mondopoint (foot length in mm).
What length_mm is: the foot length each size is made for (foot_length), the longest foot for the size (foot_length_max, “up to 25.5 cm”), or the shoe’s inside (last) length (last_length).
One size (and width fitting) of a footwear size chart. Lengths in millimetres.
object
The size’s label in each system the brand uses, e.g. {“eu”: “40”, “uk”: “6.5”}. The label in the chart’s size_system is the size shoppers and the store see.
object
The length the chart’s basis names (foot length, longest foot, or the shoe’s inside length).
Optional width fitting, e.g. narrow, regular, wide, E, EE. Rows of one size share its length.
Optional width at the ball (inside the shoe, or the foot width the fitting is made for).
Optional ball girth.
Waistband of trousers, shorts, skirts and leggings: true = elastic pull-on waistband, false = fixed band (button or zip), null or absent = not stated. Giving waist_extended_width in the POM table implies elastic. Ignored (with the warning elastic_waist_ignored) for other categories.
True when elastic_waist was inferred from text (product name, fabric, description) rather than stated by the brand.
Bottoms (jeans, trousers, shorts, skirt, leggings): where the waistband is worn, low, mid or high rise; null or absent = not stated. Ignored (with the warning worn_at_ignored) for other categories.
True when rise_type was inferred from text (product name, description) rather than stated by the brand.
Bottoms: height of the waistband top relative to the natural waist, mm, negative = below. Null or absent = derived from the rise measurements.
Responses
Section titled “Responses”Draft created
object
The garment type; it sets which POMs are needed (footwear has a size chart instead).
The designer’s intended silhouette; sets the ease targets the fit judgement compares against.
Garment measurements per size: size label → POM code → millimetres. Widths are flat half-measurements. See GET /v1/studio/garment_dictionary for codes and plausible ranges.
object
object
How the POM table was derived: the base size’s values plus, per POM, the increment (mm) between each pair of consecutive sizes (len = number of sizes - 1). The table stays the source of truth.
object
object
What the tech pack / mill sheet says.
object
object
Areal density, g/m².
Stretch along the warp (lengthwise), percent.
Stretch along the weft (crosswise), percent.
What still blocks publishing (errors) or deserves a look (warnings).
object
E.g. out_of_range, not_graded, missing_pom, composition_total
Category | fit_intent | sizes | poms | grading | import | fabric.
The values in message, for clients that word the finding in their own language (keys depend on code, e.g. value_mm, min_mm, max_mm, prev_size, fiber, max). Numbers are plain decimals (“.” separator); lengths in mm.
object
English text; clients in other languages can word it from code, size, pom and params.
Spec-sheet tolerance per POM code, ± mm (e.g. {“chest_width”: 10}). Optional; the flat preview uses ±5 mm when a POM has none.
object
Where the POM table came from, kept for audit. Set by Studio’s paste/import.
object
A footwear version’s size chart (category footwear). The version’s sizes must be the chart’s labels in the chart’s size_system, in row order (fittings collapsed). Footwear has no POMs and no 3D fit check.
object
Sets the room left in front of the toes that a size is chosen for.
A shoe size system: eu (Paris points), uk, us_men, us_women, or mondopoint (foot length in mm).
What length_mm is: the foot length each size is made for (foot_length), the longest foot for the size (foot_length_max, “up to 25.5 cm”), or the shoe’s inside (last) length (last_length).
One size (and width fitting) of a footwear size chart. Lengths in millimetres.
object
The size’s label in each system the brand uses, e.g. {“eu”: “40”, “uk”: “6.5”}. The label in the chart’s size_system is the size shoppers and the store see.
object
The length the chart’s basis names (foot length, longest foot, or the shoe’s inside length).
Optional width fitting, e.g. narrow, regular, wide, E, EE. Rows of one size share its length.
Optional width at the ball (inside the shoe, or the foot width the fitting is made for).
Optional ball girth.
Waistband: true = elastic pull-on, false = fixed band (button or zip), null = not stated.
True when elastic_waist was inferred from text, not stated by the brand.
The fit group (garments row) this version belongs to (absent until grouped).
Where the waistband is worn (bottoms); null = not stated.
True when rise_type was inferred from text, not stated by the brand.
Height of the waistband top relative to the natural waist, mm, negative = below; null = derived from the rise measurements.
Example
{ "status": "draft", "category": "tshirt", "fit_intent": "skinny", "fabric": { "construction": "jersey", "composition": [ { "fiber": "cotton" } ] }, "issues": [ { "severity": "error" } ], "spec_source": { "kind": "manual" }, "footwear": { "shoe_type": "sneaker", "size_system": "eu", "basis": "foot_length" }, "rise_type": "low"}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"}Not found
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"}Conflicts with the current state (duplicate SKU, editing a published version)
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"}Values to fix (each issue points at the field, size and POM)
object
object
E.g. out_of_range, not_graded, missing_pom, composition_total
Category | fit_intent | sizes | poms | grading | import | fabric.
The values in message, for clients that word the finding in their own language (keys depend on code, e.g. value_mm, min_mm, max_mm, prev_size, fiber, max). Numbers are plain decimals (“.” separator); lengths in mm.
object
English text; clients in other languages can word it from code, size, pom and params.
Example
{ "issues": [ { "severity": "error" } ]}Was this page helpful?
Thank you. We read every answer.