Record a return of an order line (idempotent by return ID and line)

POST

/v1/returns

curl --request POST \
  --url https://api.tryyoursize.com/v1/returns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "id": "example", "order_id": "example", "line_id": "example", "quantity": 1, "reason": "example", "exchange": true, "exchange_size": "example", "returned_at": "2026-04-15T12:00:00Z" }'

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

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

Secret key, or a restricted key with returns:write (e.g. a returns platform). The order must have been sent first (404 otherwise). Reasons are normalised to TryYourSize’s taxonomy.

Authorizations

• SecretKey

Request Body^required

Media typeapplication/json

A return of (part of) an order line. Idempotent by (line, id). Free-text notes are not accepted.

object

id

required

Your return (or RMA) ID.

string

<= 200 characters

order_id

required

string

<= 200 characters

line_id

required

string

<= 200 characters

quantity

required

integer

>= 1 <= 1000

reason

Size_too_small, size_too_large, fit_other, style, quality, damaged_or_wrong, changed_mind, other; Shopify’s ReturnReason codes (SIZE_TOO_SMALL…) and common returns-platform words are mapped. Empty: unspecified.

string

<= 60 characters

exchange

The item was exchanged rather than refunded.

boolean

exchange_size

The size sent in exchange (implies exchange).

string

<= 40 characters

returned_at

required

string format: date-time

Example ^generated

{
  "id": "example",
  "order_id": "example",
  "line_id": "example",
  "quantity": 1,
  "reason": "example",
  "exchange": true,
  "exchange_size": "example",
  "returned_at": "2026-04-15T12:00:00Z"
}

Responses

200

Updated

Media typeapplication/json

object

created

required

boolean

reason

required

The reason as normalised to TryYourSize’s taxonomy.

string

Example ^generated

{
  "created": true,
  "reason": "example"
}

201

Created

Media typeapplication/json

object

created

required

boolean

reason

required

The reason as normalised to TryYourSize’s taxonomy.

string

Example ^generated

{
  "created": true,
  "reason": "example"
}

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

404

Not found

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