Start a new draft garment version

POST

/v1/products/{product}/garments

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"}}'
};

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" } }'

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

SecretKey

Parameters

Path Parameters

product

required

string

>= 1 characters <= 120 characters

The product: its TryYourSize ID (UUID) or the brand’s SKU / style ID (external_id). An ID is looked up first.

Header Parameters

Idempotency-Key

string

>= 1 characters <= 255 characters

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 Body^required

application/json

object

category

required

The garment type; it sets which POMs are needed.

string

Allowed values: tshirt shirt sweater jacket dress skirt jeans trousers shorts leggings polo hoodie

fit_intent

required

The designer’s intended silhouette; sets the ease targets the fit judgement compares against.

string

Allowed values: skinny slim regular relaxed oversized

sizes

required

Size labels, smallest to largest.

Array<string>

poms

required

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

key

additional properties

object

key

additional properties

number format: double

grading

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

base_size

required

string

increments_mm

required

object

key

additional properties

Array<number>

fabric

required

What the tech pack / mill sheet says.

object

name

string

construction

string

Allowed values: jersey rib interlock fleece pique plain_weave twill denim satin other

composition

required

Array<object>

object

fiber

required

string

Allowed values: cotton polyester elastane viscose modal lyocell wool linen polyamide silk acrylic other

pct

required

number format: double

weight_gsm

Areal density, g/m².

number format: double

stretch_warp_pct

Stretch along the warp (lengthwise), percent.

number format: double

stretch_weft_pct

Stretch along the weft (crosswise), percent.

number format: double

notes

string

import_id

Pattern import linked to this version (omit to unlink).

string format: uuid

season

Season tag, e.g. “SS27”.

string

<= 40 characters

tolerances_mm

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

key

additional properties

number format: double

spec_source

Where the POM table came from, kept for audit. Set by Studio’s paste/import.

object

kind

required

string

Allowed values: manual paste xlsx csv pdf workbook clo browzwear

filename

string

<= 255 characters

Responses

201

Draft created

application/json

object

required

string format: uuid

product_id

required

string format: uuid

version

required

integer

status

required

string

Allowed values: draft published retired

category

required

The garment type; it sets which POMs are needed.

string

Allowed values: tshirt shirt sweater jacket dress skirt jeans trousers shorts leggings polo hoodie

fit_intent

required

The designer’s intended silhouette; sets the ease targets the fit judgement compares against.

string

Allowed values: skinny slim regular relaxed oversized

sizes

required

Array<string>

poms

required

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

key

additional properties

object

key

additional properties

number format: double

grading

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

base_size

required

string

increments_mm

required

object

key

additional properties

Array<number>

fabric

required

What the tech pack / mill sheet says.

object

name

string

construction

string

Allowed values: jersey rib interlock fleece pique plain_weave twill denim satin other

composition

required

Array<object>

object

fiber

required

string

Allowed values: cotton polyester elastane viscose modal lyocell wool linen polyamide silk acrylic other

pct

required

number format: double

weight_gsm

Areal density, g/m².

number format: double

stretch_warp_pct

Stretch along the warp (lengthwise), percent.

number format: double

stretch_weft_pct

Stretch along the weft (crosswise), percent.

number format: double

notes

string

import_id

string format: uuid

issues

required

What still blocks publishing (errors) or deserves a look (warnings).

Array<object>

object

severity

required

string

Allowed values: error warning

code

required

E.g. out_of_range, not_graded, missing_pom, composition_total

string

field

required

string

size

string

pom

string

params

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

key

additional properties

string

message

required

English text; clients in other languages can word it from code, size, pom and params.

string

created_at

required

string format: date-time

updated_at

required

string format: date-time

published_at

string format: date-time

season

string

tolerances_mm

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

key

additional properties

number format: double

spec_source

Where the POM table came from, kept for audit. Set by Studio’s paste/import.

object

kind

required

string

Allowed values: manual paste xlsx csv pdf workbook clo browzwear

filename

string

<= 255 characters

fit_group_id

The fit group (garments row) this version belongs to (absent until grouped).

string format: uuid

Example

{
  "status": "draft",
  "category": "tshirt",
  "fit_intent": "skinny",
  "fabric": {
    "construction": "jersey",
    "composition": [
      {
        "fiber": "cotton"
      }
    ]
  },
  "issues": [
    {
      "severity": "error"
    }
  ],
  "spec_source": {
    "kind": "manual"
  }
}

400

Invalid request

application/json

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

error

required

string

status

required

integer

code

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.

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}

401

Missing or invalid credentials

application/json

object

error

required

string

status

required

integer

code

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}

403

Not allowed

application/json

object

error

required

string

status

required

integer

code

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}

404

Not found

application/json

object

error

required

string

status

required

integer

code

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}

409

Conflicts with the current state (duplicate SKU, editing a published version)

application/json

object

error

required

string

status

required

integer

code

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}

422

Values to fix (each issue points at the field, size and POM)

application/json

object

error

required

string

status

required

integer

issues

required

Array<object>

object

severity

required

string

Allowed values: error warning

code

required

E.g. out_of_range, not_graded, missing_pom, composition_total

string

field

required

string

size

string

pom

string

params

object

key

additional properties

string

message

required

English text; clients in other languages can word it from code, size, pom and params.

string

Example

{
  "issues": [
    {
      "severity": "error"
    }
  ]
}

Was this page helpful?

Need help?support@tryyoursize.comWhat changed?ChangelogUsing an AI assistant?llms.txt

Start a new draft garment version

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

400

Example

401

Example

403

Example

404

Example

409

Example

422

Example

Request Body^required