API reference

GET /v1/brands/{brand_id}/client

The client of a brand (for createWidget with brand_id only)

Public, cacheable 1 hour. An unknown brand, or one of a paused or churned client, answers 404 brand_not_found.

GET /v1/plugins/customization

Widget customization (theme and texts) of a client

Browsers may cache it 5 minutes; the CDN never does (D40). From a domain the client does not allow, the answer is {eligible:false, reason:"not_whitelisted"} (D39).

GET /v1/plugins/origin_check

Is the page that framed the widget iframe an allowed domain of the client?

Called once per page load by the iframe (T13.03.01) before it talks to the parent page. Exact host or wildcard subdomain, as CORS; www. and no www. differ unless both are listed, and http: pages count only outside production. Never cached. From a domain the client does not allow, the answer is {allowed:false, reason:"not_whitelisted"} (D39).

GET /v1/plugins/frame_policy

Which pages may frame the widget iframe of a client (frame-ancestors)

Asked by the plugin host for every iframe page request (T13.03.02), which copies the value into the page's Content-Security-Policy: frame-ancestors. The same origins the origin check allows: https://<host> for each allowed domain, https://*.<host> for a wildcard, plus https://admin.shopify.com for a Shopify client (theme editor), plus the environment's back-office origin for every serving client (its live and reference previews frame the same page). An unknown, malformed or not-serving client gets 'none'. Also sent in the X-Fmt-Frame-Ancestors header. Never cached; follows a domain change within 60 s.

GET /v1/sizing_charts/{id_or_slug}

One size chart, published version, in the shape the widget and the engine read

By numeric id or unique name. Cached 5 minutes by the CDN and browsers, purged when the chart is published or deleted. An unknown chart, a chart of another client, a chart never published, or a paused or churned client answers 404 (never cached). From a domain the client does not allow, the answer is {eligible:false, reason:"not_whitelisted"} (D39).

GET /v1/plugin_references

Reference brands for the shopper reference step, most used first

The D19-compatible wire format (D91): type_of_references is cloth, shoe or head; the answer maps brand name → category slug → reference products, with most_used_brands (default 5, at most 20) and client_brand. With the client's plugin_use_client_references flag on and a non-empty list, only those brands in the merchant's order. Readable from any origin (*) and cached 10 minutes, keyed by the full URL. An unknown or paused client answers 404, a bad gender or type 422 naming the field, the database down 503 (errors never cached). From a domain the client does not allow: {eligible:false, reason:"not_whitelisted", references:{}, most_used_brands:[], client_brand:null} (D39).

GET /v1/plugin_sizing_charts

A reference brand's published size charts for a category and gender

Only the reference catalogue's published, current charts of the brand (a merged brand answers for the kept one), for the shopper's gender and unisex (children: their own gender only), each with its size systems and sizes. An unknown brand or category answers []; no brand_id 422. Readable from any origin (*), cached 10 minutes. From a domain the client does not allow: {eligible:false, reason:"not_whitelisted"} (D39).

GET /v1/sizes

The size system catalogue (EU, FR, UK, US, … and shoe scales)

The same for every shop: no client_id, readable from any origin (Access-Control-Allow-Origin: *), cached 5 minutes by the CDN and browsers. Ids never change (EU is 2). There is no write route (405). The catalogue unreadable answers 503 (never cached).

GET /v1/products/plugin_info

Is this product eligible, and the widget's set-up for it (compatible keys, then ours)

The compatible answer (D19, CONTRACTS §1.1) with our keys added after it; each field's description starts with D19 compatible: or Added:. Not eligible: only {eligible:false, reason} (D50 reasons). From a domain the client does not allow, from an unknown client, or without Origin (curl, a server), the answer is {eligible:false, reason:"not_whitelisted"} (D39). An eligible answer may be kept 60 s by the browser; the CDN never keeps it (D52). The database down answers 503 with Retry-After.

PUT /wrong_sizing_chart_products

Report that a product page's sizes do not match its size chart

Unchanged legacy path. The body is optional (the legacy SDK sends none): {page_sizes, status}, at most 200 sizes. The server computes the status itself with the shared size match. One report per product per day is kept (later ones update it). An unknown client or product, a paused client, or a domain the client does not allow is dropped with a 200 (D39).

Request body: application/json, text/plain

GET /v1/cross_sell_products

Suggested products for one cross-sell tab, with the shopper's size (compatible query)

One tab of suggested products for the product page (S07.12, D125), at most 12, each with the size the reco engine gives this profile on that product (null when it has no chart or the engine cannot decide). Latest releases: the same gender (and unisex) and body part, newest first. You might like: the same feed category, the same size chart first. Bought by people like you: kept by at least 5 shoppers close in gender, age, height and weight (training rows of S05.05), most kept first. Bought together: kept in at least 2 of the same orders, most shared orders first; full returns do not count. Only published products still in the feed, with a size in stock and an https page on an allowed domain of the client; never the current product. The cross-sell flag off or no match answers an empty list. An unknown product or chart answers {eligible:false, reason:"unknown_product"} like plugin_info; from a domain the client does not allow, or without Origin, {eligible:false, reason:"not_whitelisted", products:[]} (D39). A bad tab or value answers 422 validation_failed with error.fields. Answers are no-store; body values are never logged. The GET form is kept for compatibility; the widget sends the POST form, so body values never travel in a URL.

POST /v1/cross_sell_products

Suggested products for one cross-sell tab, with the shopper's size (JSON body)

One tab of suggested products for the product page (S07.12, D125), at most 12, each with the size the reco engine gives this profile on that product (null when it has no chart or the engine cannot decide). Latest releases: the same gender (and unisex) and body part, newest first. You might like: the same feed category, the same size chart first. Bought by people like you: kept by at least 5 shoppers close in gender, age, height and weight (training rows of S05.05), most kept first. Bought together: kept in at least 2 of the same orders, most shared orders first; full returns do not count. Only published products still in the feed, with a size in stock and an https page on an allowed domain of the client; never the current product. The cross-sell flag off or no match answers an empty list. An unknown product or chart answers {eligible:false, reason:"unknown_product"} like plugin_info; from a domain the client does not allow, or without Origin, {eligible:false, reason:"not_whitelisted", products:[]} (D39). A bad tab or value answers 422 validation_failed with error.fields. Answers are no-store; body values are never logged. The same names as the GET query, as a JSON body; numbers as numbers.

Request body: application/json, text/plain

GET /v1/integration_check

Counts of the integration events seen in the last 15 minutes

The docs snippet generator's Verify button (T12.08.04). Counts of product, cart and transaction_end events this client sent in the last 15 minutes, with test and invalid events counted apart; never any event data. Browser calls only from the docs origin. Answers are no-store: poll every 5 s. Limited to 30 calls a minute per IP (429 with Retry-After). A missing or non-numeric client_id answers 422 validation_failed with error.fields; an unknown client answers 404 not_found.

POST /v1/legal/subprocessor-subscriptions

Subscribe an email address to sub-processor changes

The sub-processor page's form (T13.04.02, D130 2). Sends a confirm email; the address gets change emails only after its link is clicked (valid 7 days). The answer is the same for a new, pending or already subscribed address and never names the address. Browser calls only from the docs origin. Limited to 5 requests per hour per IP, 3 per day per address and 500 per day in total (429 with Retry-After). A bad address answers 422 validation_failed with error.fields and field_errors.

Request body: application/json, text/plain

POST /v1/legal/subprocessor-subscriptions/confirm

Confirm a sub-processor change subscription

The confirm link of the email (T13.04.02-TC11). Docs origin only for browsers.

Request body: application/json, text/plain

POST /v1/legal/subprocessor-subscriptions/unsubscribe

Stop sub-processor change emails and delete the address

The one-click unsubscribe link of every change email (T13.04.02-TC12). The address is deleted at once. Docs origin only for browsers.

Request body: application/json, text/plain

POST /v1/reco/clothes

Size-chart (classic) size recommendation for clothes: the D19-compatible answer keys, then ours (CONTRACTS §8)

From a shop page on an allowed domain of client_id (or a server with a recommend API key); anyone else gets {eligible:false, reason:"not_whitelisted", comfort:[]} (D39). Values outside the widget limits, unknown genders or shapes, unknown tape keys and a ± over 5 cm answer 422 validation_failed with error.fields (never the values). An unknown or not-eligible product, or a paused client, answers 404 product_not_eligible with its D50 reason. 60 calls a minute per tracking_id (429), on top of the client + IP limit. Answers are no-store; nothing the shopper sent is logged or stored. The database down answers 503. Quick answers go to the body-service predictor (sd per dimension); tape values in measurements_cm are used as entered (uncertainty_cm, default 1). comfort[0] is recommended_size ?? closest_size; status is recommended, between_sizes, needs_measurements (also when the predictor is down or untrained) or no_match. available never changes the pick. size_conversions (contract v2) holds every chart size in up to 3 other systems, the shop_country's system first. auto: true marks the silent page-load reco: the same answer, counted apart, and an incomplete saved profile answers needs_measurements instead of 422.

Request body: application/json, text/plain

POST /v1/reco/shoes

Foot-length size recommendation: shoes (CONTRACTS §8, S05.07)

From a shop page on an allowed domain of client_id (or a server with a recommend API key); anyone else gets {eligible:false, reason:"not_whitelisted", comfort:[]} (D39). Values outside the widget limits, unknown genders or shapes, unknown tape keys and a ± over 5 cm answer 422 validation_failed with error.fields (never the values). An unknown or not-eligible product, or a paused client, answers 404 product_not_eligible with its D50 reason. 60 calls a minute per tracking_id (429), on top of the client + IP limit. Answers are no-store; nothing the shopper sent is logged or stored. The database down answers 503. foot_length (cm, 10–34) is matched with the product's feet chart, ±0.25 cm (D111); a chart that gives the shoe's inner length adds the toe allowance (0.5–1.0 cm). Without it, adult male / female get an estimate from height (source: predicted, a larger ±), moved by shoe references (type_of_references=shoe); with no height, shoe references alone give it; children and unisex without a foot length answer needs_measurements. With none of foot length, height or a reference: 422 naming foot_length. A product that is not feet is a 422 naming product_id. One zone, FootLength (TOO_TIGHT = too short … TOO_LOOSE = too long); between two sizes the size where the foot is too short is never first. The §8 shape with mode: shoes, no deciding_measurement, no morph_params.

Request body: application/json, text/plain

POST /v1/reco/head

Head-circumference size recommendation: helmets and hats (CONTRACTS §8, S05.07)

From a shop page on an allowed domain of client_id (or a server with a recommend API key); anyone else gets {eligible:false, reason:"not_whitelisted", comfort:[]} (D39). Values outside the widget limits, unknown genders or shapes, unknown tape keys and a ± over 5 cm answer 422 validation_failed with error.fields (never the values). An unknown or not-eligible product, or a paused client, answers 404 product_not_eligible with its D50 reason. 60 calls a minute per tracking_id (429), on top of the client + IP limit. Answers are no-store; nothing the shopper sent is logged or stored. The database down answers 503. head_circumference (cm; adults 50–65, boys / girls 48–58, babies 40–58) is matched with the product's head chart, ±0.5 cm (D109). It is never estimated from height or weight: without it a helmet reference (type_of_references=head) gives it, and with neither the answer is 422 naming head_circumference. A product that is not head is a 422 naming product_id. One girth zone, HeadCircumference. The §8 shape with mode: head, no deciding_measurement, no morph_params.

Request body: application/json, text/plain

POST /v1/reco/social_proof

Social-proof size recommendation: sizes kept by similar shoppers (CONTRACTS §8, S05.05)

From a shop page on an allowed domain of client_id (or a server with a recommend API key); anyone else gets {eligible:false, reason:"not_whitelisted", comfort:[]} (D39). Values outside the widget limits, unknown genders or shapes, unknown tape keys and a ± over 5 cm answer 422 validation_failed with error.fields (never the values). An unknown or not-eligible product, or a paused client, answers 404 product_not_eligible with its D50 reason. 60 calls a minute per tracking_id (429), on top of the client + IP limit. Answers are no-store; nothing the shopper sent is logged or stored. The database down answers 503. For clothes, shoes and headwear in social-proof mode (the product's reco_mode override, or the client's default mode): gender, age, height and weight are required, foot_length / head_circumference sharpen shoes and headwear, sizing_chart_slug is null. The shares come from the shopper's nearest neighbours (same gender, about 50) among the shoppers who kept the product, falling back to its category + body part, then its body part; social_proof_sizes lists them best first, rounded to 2 decimals and summing to 1, and the top one is recommended_size (available: false when out of stock; no other size is swapped in). The older widget keys first_size, second_size, size_conversions, primary_system and sizing_chart_id (null without a chart) are kept. Fewer than the configured minimum (default 30) similar shoppers at every level, or no training data yet, answer status: no_match with message_key: SORRY_SOCIAL_PROOF, empty social_proof_sizes and null first_size / second_size. A product that is not in social-proof mode answers 404 product_not_eligible with reason: not_social_proof. Shares change only after the next daily training run; training data that cannot be read answers 503.

Request body: application/json, text/plain

POST /v1/reco/usual_size

Usual-size recommendation: the shopper's usual size moved by fit feeling and desired fit (CONTRACTS §8)

From a shop page on an allowed domain of client_id (or a server with a recommend API key); anyone else gets {eligible:false, reason:"not_whitelisted", comfort:[]} (D39). Values outside the widget limits, unknown genders or shapes, unknown tape keys and a ± over 5 cm answer 422 validation_failed with error.fields (never the values). An unknown or not-eligible product, or a paused client, answers 404 product_not_eligible with its D50 reason. 60 calls a minute per tracking_id (429), on top of the client + IP limit. Answers are no-store; nothing the shopper sent is logged or stored. The database down answers 503. The usual size (one of plugin_info.usual_size_list, read in size_system_id or else the product's preferred system) moves by the fit answers: narrow and oversize +½ size, comfy and slim −½, plus the product's own offset, rounded away from zero, at most ±2 (D89). A sizing_adjustment sent here is ignored. Answers the §8 shape with mode: usual_size and the D19 keys found, name, size_order, precision, plus is_usual_size and offset_applied. A name outside the list, or an unknown size_system_id, is a 422 naming the field. Needs no predictor.

Request body: application/json, text/plain

POST /events

Send one tracking event, an array or {events:[…]} of up to 50 (64 KiB)

One event {client_id, event, tracking_id, …} (the compatible form, D19), a JSON array or {events:[…]}. text/plain (sendBeacon) is read as JSON. The call is queued and answered 202 {received, accepted, rejected} (D72); events are validated, enriched and stored by the workers. An unknown event is listed in rejected (a single event: 400 unknown_event); an event_id already sent with other data is event_id_conflict (a single event: 409). An unknown client answers 400 unknown_client; a bot or a paused client is dropped with a 2xx. Events from a domain the client does not allow are dropped with a 200 (D39). Limits: the per-call limit plus 200 events/s per tracking_id and 5,000 events/s per client (429). The queue down answers 503 queue_unavailable; another content type 415.

Request body: application/json, text/plain

POST /debug

Integration-script heartbeat and debug events (__debug__)

Same body forms, limits, origin rules and answer as POST /events; every item is stored as a __debug__ event (kept 7 days).

Request body: application/json, text/plain

POST /events/mixpanel/{name}

Product-analytics proxy: one UX event under its name (the compatible sendMixpanelEvent)

The compatible body {payload: {client_id, tracking_id, …event fields}, mixpanel_properties: {$referrer, $screen_width, $screen_height, utm_source}}; only those four page properties are kept. The name (URL-encoded) is a catalogue event name or a mapped older product-analytics name (Plugin Opened → plugin_open, Size Validated → size_validated, …); any other name is listed in rejected as unknown_event (202). The event then goes through the same intake as POST /events (origin rules and the D39 soft refusal, bots, rate limits, 64 KiB, the queue) and is stored like it (ux events are kept 90 days). No vendor is called in the request: with the client's analytics forwarding on, the worker forwards stored UX events later (T08.08.02).

Request body: application/json, text/plain

POST /events/pixel/shopify

Shopify Web Pixel event (cart, checkout)

Sent from Shopify's pixel sandbox, so the body's origin (the shop page) must be an allowed domain of client_id; otherwise the event is dropped with a 200. An optional ingest_key is verified when sent: a wrong one answers 401 invalid_ingest_key. Accepted events are queued (202) like POST /events; checkout becomes transaction_end.

Request body: application/json, text/plain

GET /v1/body/schema

The measurement vocabulary (ids, label keys, groups, ranges, definitions) and the body model version

Served from memory, built once per model version from the shared vocabulary; fitter-only dimensions (pelvisGirth) are left out. ETag names the model version and a digest of the vocabulary; cached 5 min. Model data with no shopper data: any origin may read it (D82). The body-service down or loading answers 503.

GET /v1/body/default

The default female or male body of the current body model (a public, immutable CDN artifact)

Without modelVersion: a 302 (cached 60 s) to ?bodyType=…&modelVersion=<current>. With it: the body-service's default-body report (params, measurements, rest joints, tape paths), Cache-Control: public, max-age=31536000, immutable, built once per body type and model version (no job per shopper). Another model version answers 404. Model data with no shopper data: any origin may read it (D82).

POST /v1/body/predict

Simple-mode answers → every body measurement with its own sd, and the live body's morph params

Anonymous shopper call from an allowed domain of client_id (D14); another origin, no Origin or an unknown or paused client is refused (403). Units are cm and kg. Synchronous, answered by the body-service predictor within 1 s (no job). Boys and girls get {status:"needs_measurements"} while the predictor has no child data. Values outside the widget's limits, unknown fields, a shape of the other gender or a bra on a male body answer 422 validation_failed with error.fields (never the values). No answer and no measurement is logged or stored. Rate limited per device (tracking_id, else client and IP): 429. The body-service down or slow answers 503; no trained predictor answers 501 predictor_not_available with accuracyValidated:false. accuracyValidated stays false until the accuracy validation (S14.09) signs off.

Request body: application/json, text/plain

POST /v1/body/fit

Fit the body to tape values in a background job (202 + the job)

Anonymous shopper call from an allowed domain of client_id (D14); another origin, no Origin or an unknown or paused client is refused (403). Needs Idempotency-Key. Answers 202 with the job and Location; poll GET /v1/body/jobs/{id} every retryAfterMs. The request and the result are stored encrypted and kept 24 h. Limits: per device (tracking_id, else client and IP; 15 a minute) and per client (429), at most 100 queued fits per client (429). The body-service down or loading answers 503.

Request body: application/json, text/plain

GET /v1/body/jobs/{id}

A body job's state (queued, running, done, failed, cancelled) and, when done, its result links

Anonymous shopper call from an allowed domain of client_id (D14); another origin, no Origin or an unknown or paused client is refused (403). Another client's job, or an unknown id, is 404; after 24 h 410. retryAfterMs (also Retry-After) is 300 ms during the first 3 s, then longer; null once final. A failed job carries an error code (invalid_request, body_service_unavailable, deadline_exceeded, fit_failed).

DELETE /v1/body/jobs/{id}

Cancel a queued or running body job

Anonymous shopper call from an allowed domain of client_id (D14); another origin, no Origin or an unknown or paused client is refused (403). A queued or running job becomes cancelled and never gets a result, even when its fit ends later. A job already done, failed or cancelled stays as it is, with cancelled: false.

GET /v1/body/results/{file}

A fitted body: <id>.glb (Y-up metres, joints as nodes), <id>.json (the fit report) or <id>.obj

Anonymous shopper call from an allowed domain of client_id (D14); another origin, no Origin or an unknown or paused client is refused (403). Only for a done job of this client (else 404); 410 after 24 h. The GLB has the feet at y=0 and, with morphs=1, one morph target per morph parameter. The JSON report holds body numbers only. The old .mtl routes are gone (404).