Server API quickstart

For your developer

What it does: Connects our backend to TryYourSize: sync products and garment data, send orders and returns for the size-return report, and read shoppers' sizes server-side. No measurements are ever sent or received.

Time needed: A few hours for a first call; a day or two for a full catalog sync.

What to send them: A test secret key (sk_test_…) from Studio → Developers → API keys, sent through a password manager, never by email or chat. For a partner, a restricted key (rk_test_…) with only the scopes it needs.

Conventions

Base URL	https://api.tryyoursize.com
Authentication	Authorization: Bearer sk_test_… (or a restricted key rk_…)
Version	TYS-Version: 2026-10-25 (see Versioning)
Errors	{ error, status, code, doc_url, request_id } plus the X-Request-ID header (see Errors)
Retries	Idempotency-Key on POST (see Idempotency)
Lists	limit + cursor → { data, has_more, next_cursor } (see Pagination)

Catalog paths take a TryYourSize product ID or your SKU. The catalog is shared by test and live mode: test answers drafts, live answers published versions.

Install

Node.jsPythoncURL

npm install @tryyoursize/node

import TryYourSize from "@tryyoursize/node";

const tys = new TryYourSize(process.env.TYS_SECRET_KEY!);

pip install tryyoursize

import os
import tryyoursize

tys = tryyoursize.TryYourSize(os.environ["TYS_SECRET_KEY"])

export TYS_SECRET_KEY=sk_test_…
curl https://api.tryyoursize.com/v1/products?limit=5 \
  -H "Authorization: Bearer $TYS_SECRET_KEY" \
  -H "TYS-Version: 2026-10-25"

Note

The Node (@tryyoursize/node) and Python (tryyoursize) libraries are our official server SDKs. They pin TYS-Version for you, retry safely with idempotency keys, and follow the API reference one to one; when in doubt, the API reference is the source of truth.

Sync a product

Node.jsPython

const product = await tys.products.create(
  { external_id: "CREW-TSHIRT", name: "Crew T-shirt", category: "tshirt" },
  { idempotencyKey: crypto.randomUUID() },
);

// Your shop's labels for each Studio size: recommendations come back in these labels.
await tys.products.sizeMap.save("CREW-TSHIRT", {
  entries: [
    { studio_size: "S", shop_value: "Small" },
    { studio_size: "M", shop_value: "Medium" },
    { studio_size: "L", shop_value: "Large" },
  ],
});

for await (const p of tys.products.list({ limit: 50 })) {
  console.log(p.id, p.external_id);
}

import uuid

product = tys.products.create(
    external_id="CREW-TSHIRT",
    name="Crew T-shirt",
    category="tshirt",
    idempotency_key=str(uuid.uuid4()),
)

tys.products.size_map.save("CREW-TSHIRT", entries=[
    {"studio_size": "S", "shop_value": "Small"},
    {"studio_size": "M", "shop_value": "Medium"},
    {"studio_size": "L", "shop_value": "Large"},
])

for p in tys.products.list(limit=50).auto_paging_iter():
    print(p["id"], p["external_id"])

Field names and bodies are in the API reference.

Resources

Node	Python	Endpoint
tys.recommendations.create({ handle, products })	tys.recommendations.create(...)	POST /v1/recommendations
tys.products.list / create / retrieve / update	same	/v1/products, /v1/products/{product}
tys.products.sizeMap.retrieve / save	tys.products.size_map.retrieve / save	/v1/products/{product}/size_map
tys.products.garments.list / createDraft	tys.products.garments.list / create_draft	/v1/products/{product}/garments
tys.garments.retrieve / updateDraft / publish	tys.garments.retrieve / update_draft / publish	/v1/garments/{garment_id}
tys.fitGroups.list / create / retrieve / linkProducts	tys.fit_groups.list / create / retrieve / link_products	/v1/fit_groups
tys.orders.create	tys.orders.create	POST /v1/orders
tys.returns.create	tys.returns.create	POST /v1/returns
tys.auditEvents.list	tys.audit_events.list	GET /v1/audit_events
tys.webhooks.constructEvent(rawBody, header, secret)	tryyoursize.Webhook.construct_event(payload, sig_header, secret)	Webhooks

Errors

Node.jsPython

import TryYourSize, { TryYourSizeError } from "@tryyoursize/node";

try {
  await tys.products.retrieve("NO-SUCH-SKU");
} catch (err) {
  if (err instanceof TryYourSizeError) {
    console.error(err.code, err.docUrl, err.requestId);   // "not_found", https://docs…/api/errors/#not_found, …
  }
}

try:
    tys.products.retrieve("NO-SUCH-SKU")
except tryyoursize.APIError as e:
    print(e.code, e.doc_url, e.request_id)

Next

• Server-side recommendations: the shopper’s size on your server.
• Orders and returns: measure size-related returns.
• Webhooks: fit.recommended, garment.published and more.