Record an order (idempotent by order ID)

POST

/v1/orders

curl --request POST \
  --url https://api.tryyoursize.com/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "id": "example", "ordered_at": "2026-04-15T12:00:00Z", "currency": "example", "visitor_id": "example", "experiment_arm": "treatment", "lines": [ { "id": "example", "product": "example", "variant": "example", "size": "example", "quantity": 1, "unit_price_minor": 1, "tys_shown": true, "recommended_size": "example", "attribution": "cart_attribute" } ] }'

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

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

From the brand’s server with a secret key or a restricted key with orders:write. Re-sending the same id updates the order (200); a new one is 201. The A/B arm comes from visitor_id (recomputed by TryYourSize) or experiment_arm. No customer data is accepted.

Authorizations

• SecretKey

Request Body^required

Media typeapplication/json

An order from the brand’s server. Re-sending the same id updates it (idempotent). No customer data: there is no customer, email, name or address field, and unknown fields are refused.

object

id

required

Your order ID.

string

<= 200 characters

ordered_at

required

string format: date-time

currency

ISO 4217, e.g. EUR.

string

visitor_id

The SDK’s anonymous visitor ID ((await tys.experiment())?.visitorId), saved with the cart. TryYourSize recomputes the A/B arm from it and stores only its hash. Never a customer ID.

string

<= 64 characters

experiment_arm

The arm, when you cannot send visitor_id.

string

Allowed values: treatment holdout

lines

required

Array<object>

>= 1 items <= 200 items

object

id

required

Your order line ID (unique within the order).

string

<= 200 characters

product

required

Your product ID (the one you pass to the SDK).

string

<= 200 characters

variant

string

<= 200 characters

size

required

The size bought, in your labels.

string

<= 40 characters

quantity

required

integer

>= 1 <= 1000

unit_price_minor

Price of one unit in minor units (5995 = 59.95). Optional; used for the refund value estimate.

integer format: int64

tys_shown

A TryYourSize element was shown for this purchase.

boolean

recommended_size

The size TryYourSize recommended (the SDK’s recommendation event, or the _tys_size cart line property).

string

<= 40 characters

attribution

Where recommended_size came from.

string

Allowed values: cart_attribute sdk api

Responses

200

Updated

Media typeapplication/json

object

id

required

string format: uuid

external_id

required

string

created

required

False when the order already existed and was updated.

boolean

experiment_arm

string

Allowed values: treatment holdout

lines

required

integer

Example

{
  "experiment_arm": "treatment"
}

201

Created

Media typeapplication/json

object

id

required

string format: uuid

external_id

required

string

created

required

False when the order already existed and was updated.

boolean

experiment_arm

string

Allowed values: treatment holdout

lines

required

integer

Example

{
  "experiment_arm": "treatment"
}

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