Create a product

POST

/v1/products

curl --request POST \
  --url https://api.tryyoursize.com/v1/products \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "external_id": "example", "name": "example", "category": "tshirt" }'

• Production (test and live mode are chosen by the key)

Key scopes: products:write. A secret key (sk_) has every scope; a restricted key (rk_) needs the scopes listed.

The SKU / style ID (external_id) is unique per store (409). Send an Idempotency-Key to retry safely.

Authorizations

• SecretKey

Parameters

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

Media typeapplication/json

object

external_id

required

string

name

required

string

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

Responses

201

Created

Media typeapplication/json

object

id

required

string format: uuid

external_id

required

The brand’s SKU or style ID (unique per brand).

string

name

required

string

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

published_version

Garment version shoppers are fitted against, if any.

integer

draft_version

Garment version being edited, if any.

integer

created_at

required

string format: date-time

updated_at

required

string format: date-time

fit_group_id

The fit group whose garment this product uses (absent until grouped).

string format: uuid

brand_id

The brand the product belongs to; every store of the brand sees it.

string format: uuid

home_store_id

The store the product was created in.

string format: uuid

retired_at

Set when the product is retired; shoppers no longer get a size for it.

string format: date-time

available

Whether the store it was read through offers it (false in the brand list, see stores).

boolean

Example

{
  "category": "tshirt"
}

400

Invalid request

Media typeapplication/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

Media typeapplication/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"
}

403

Not allowed

Media typeapplication/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"
}

409

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

Media typeapplication/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"
}