Changelog

Every change to the public API, newest first. Each entry names the date and the hash of the API spec it produced. The API reference always shows the current spec. Event catalogue changes are at the end.

1. 2026-11-02 d931b77a2a4b

   • plugin_info adds garment_look (base | tee | null, D131 3): tee = the CC0 T-shirt look of a top product (category says t-shirt / tee / singlet, or the merchant picked "T-shirt"); null when garment_type is null.
   • Reco answers add candidates[].comparisons[].garment_cm (optional, D131 4): on a garment chart, the chart's garment measurement of that size (cm), for the 3D garment's ease. Absent on body charts.

2. 2026-11-02 6a4f79290de8

   • New POST /v1/legal/subprocessor-subscriptions {email} (T13.04.02, D130 2): the sub-processor page's subscribe form. Always 202 {status: "pending"} (never says whether the address was known); a confirm email is sent and the address counts only after its link. Docs origin only for browsers; 5 per hour per IP, 3 per day per address, 500 per day in total (429 with Retry-After); a bad address answers 422 validation_failed with error.fields.
   • New POST /v1/legal/subprocessor-subscriptions/confirm and /unsubscribe {token}: the email links. 200 {status}, or 404 not_found for an unknown, used or expired link. Unsubscribing deletes the address.

3. 2026-11-02 bf9e4fbb4327

   • New GET /v1/integration_check?client_id= (T12.08.04): the docs snippet generator's Verify button. Counts of product, cart and transaction_end of the last 15 minutes (count, test, invalid per event), never event data. Docs origin only for browsers, no-store, 30 calls a minute per IP (429 with Retry-After); a bad client_id answers 422 validation_failed with error.fields, an unknown client 404 (D130 8).

4. 2026-11-02 3d616ab5f8b4

   • New GET /v1/body/garments/{template} (T14.14.02, D127–D129): a garment GLB bound to the body model (bodyType, lod=1, look=base|tee, modelVersion), 302 to the current model version, then public, immutable, any origin, brotli else gzip. New error code garment_not_built (404) for shoe and helmet.

5. 2026-11-02 a99313226cd6

   • POST /v1/reco/social_proof: description wording only (the older widget keys); no schema change.

6. 2026-11-02 617d8f988528

   • GET /v1/products/plugin_info: new added key garment_type (T14.14.09): top, jacket, tights, shorts, one_piece, shoe, helmet or null, the 3D garment template of the product (merchant pick, else the linking rule's, else derived from the category). Additive; Fitle's keys are unchanged.

7. 2026-11-02 de2e4dac9201

   • POST /v1/body/fit takes an optional population {age?, heightCm?, weightKg?, bodyShape?, sdCm?} (D126, re-predict body): the free dimensions are predicted again from the locks (a missing weight or height inferred from them) and the fit pulls them by their sd, so raising the waist alone gives a heavier body everywhere. The fit report then carries population {predictorVersion, weightKg, weightInferred, heightCm, heightInferred, softCm, predictedCm}. Additive; without the field the fit is unchanged.

8. 2026-11-02 ec902a225f83

   • POST /events/mixpanel/{name} is documented (S08.08, T08.08.02): the compatible product-analytics proxy body {payload, mixpanel_properties}, catalogue names and mapped older names (others unknown_event), the same intake as POST /events; stored UX events are forwarded later by the worker when the client has analytics forwarding.

9. 2026-11-02 dde2ae376f7c

   • POST /v1/reco/social_proof is built (S05.05, T05.05.03): it answers the §8 recommendation with mode: social_proof, social_proof_sizes (best first, 2 decimals, summing to 1), Fitle's first_size, second_size, primary_system ({name}) and sizing_chart_id (null without a chart), plus ratio_high, social_proof_level and social_proof_samples. Too little history answers status: no_match with the new message key SORRY_SOCIAL_PROOF; a product not in social-proof mode answers 404 product_not_eligible with reason: not_social_proof. The 501 mode_not_available answer and error code are removed.
   • Reco answers: chart_id and chart_revision may be null (a social-proof product with no chart). Contract version unchanged (no field removed).
   • New GET and POST /v1/cross_sell_products (S07.12, T07.12.01, D125): one cross-sell tab (cross_sell_products_type: recentProducts, similarProducts, boughtBySimilarPeopleProducts, boughtTogetherProducts) with Fitle's query names; the POST takes the same names as a JSON body. Answers {eligible:true, type, products:[{id, name, image, url, price, currency, size}]} (at most 12), the D39 soft refusal with products: [], or {eligible:false, reason:"unknown_product", products:[]}; bad values 422 validation_failed with error.fields.

10. 2026-10-30 4feab004389d

    • GET /v1/plugins/frame_policy (T13.03.02-TC19): a serving client's frame_ancestors also lists the environment's back-office origin (PUBLIC_ADMIN_URL), so the back office's live and reference-brands previews can frame the iframe page. Unknown and not-serving clients still get 'none'.

11. 2026-10-30 301742c25547

    • New GET /v1/plugins/frame_policy?cid= (T13.03.02, D118): the frame-ancestors value for a client's widget iframe page ({frame_ancestors} and the X-Fmt-Frame-Ancestors header). The plugin host's ingress copies it into the iframe page's Content-Security-Policy; 'none' for an unknown, malformed or not-serving client.

12. 2026-10-29 0b2ade28a274

    • POST /events/pixel/shopify (T08.04.01): client_id may also be a number written as text (Fitle's documented pixel sends '<client_id>', D19); tracking_id, shop_country, product_id and variant_id may be null (Fitle's pixel sends tracking_id: null when the shop has no device id; the order is stored untracked).

13. 2026-10-29 f94b7d8e7abe

    • New POST /v1/shopify/session (T12.01.01, T12.01.02): the Shopify app opens with its session token; the first open installs (token exchange, client link, metafield, web pixel, first import) and the answer is the shop's state. New POST /v1/shopify/webhooks: Shopify's app/uninstalled, app/scopes_update and GDPR webhooks, HMAC-checked, 200 or 401 with an empty body.

14. 2026-10-29 37ad0addeadf

    • New GET /v1/shopify/app (the Shopify app's embedded home page, HTML) and GET /v1/shopify/home/status (its 5 setup checks for the shop of the Shopify session token; JSON, or HTML with Accept: text/html), and POST /v1/shopify/home/dashboard-link (the app home's one-time back-office sign-in link), T12.01.05.
    • New POST /v1/shopify/setup-requests (T12.01.06): the docs site's white-glove Shopify form. 201 with the ops ticket (never the collaborator request code); docs origin only; rate limited; 422 validation_failed with a field_errors map.

15. 2026-10-28 8dc9b53004f8

    • POST /v1/reco/shoes: a typed foot_length is matched ±0.25 cm (D111), no longer ±0.5 cm; a typed head_circumference stays ±0.5 cm. Description text only.

16. 2026-10-28 979e53c4a963

    • POST /v1/reco/shoes and POST /v1/reco/head are built (S05.07): they answer the §8 recommendation with mode: shoes / mode: head and no longer list 501 mode_not_available. foot_length is optional with height or a shoe reference (10–34 cm); head_circumference is optional with a helmet reference (adults 50–65, children 48–58, babies 40–58 cm). Both accept age, height and weight with the clothes limits. One example each added.
    • POST /events and /debug items (T08.01.01, D110): the event catalogue's envelope adds the optional event_id, schema_version (1), instance_id, product_id, brand_id, product_associated, ab_data, testEvent and extra, with limits (user_agent ≤ 2,048, shop_country ≤ 8, channel ≤ 64 characters).

17. 2026-10-28 601bb5a44b8c

    • GET /v1/products/plugin_info: new key fit_preferences (the ease profiles of a garment chart, [] for body charts, D105); sizing_adjustment is the product's merchant offset (−1, 0, +1; T04.07.03, D104), still a number; usual_size_list (with its system and id) is also sent for every product with a chart when the merchant shows the usual-size path (D105).
    • POST /v1/reco/clothes: a product with a merchant offset answers offset_applied and sizing_adjustment (the descriptions of both fields now cover classic answers; T04.07.03).

18. 2026-10-28 eda81ad2782a

    • Every public route is on /v1 (D102); the old paths are removed, with no aliases. POST /v3/reco/clothes → POST /v1/reco/clothes; GET /v2/plugins/customization → GET /v1/plugins/customization; GET /v2/plugin_references → GET /v1/plugin_references; GET /v2/plugin_sizing_charts → GET /v1/plugin_sizing_charts; GET /v2/sizes → GET /v1/sizes; GET /v2/sizing_charts/{id_or_slug} → GET /v1/sizing_charts/{id_or_slug}; GET /v2/body/morph_basis → GET /v1/body/morph_basis. Request and answer bodies, auth, CORS, caching and limits do not change; X-Api-Version is v1 on every route.

19. 2026-10-28 3e7636fadfab

    • Reco answers add deciding_measurement (D98, T07.09.09; an added optional field, contract version stays 2): the predicted primary measurement (vocabulary id) whose tape value would most raise the chance of the right size, or null. The engine is chart-fit-3.0 (D97, T05.03.07): the size is the most likely one in which no primary measurement is tight; the answer's shape does not change.

20. 2026-10-27 c903bf25a50e

    • Added GET /v2/plugin_references?gender=&type_of_references=cloth|shoe|head&client_id=&number_of_most_used= and GET /v2/plugin_sizing_charts?client_id=&gender=&status=active&brand_id=&category= (S04.05 T04.05.02, D91): Fitle's wire format ({references, most_used_brands, client_brand}; the brand's charts with size_systems), *, cached 10 minutes; the D39 soft refusal for a refused origin; 422 naming the field for a bad query.
    • Reco answers add incoherent_references: [{index, reason}] (T05.04.03, D91; an added field, contract version stays 2): references that contradict the body data or each other, by their place in the request's references; reason is one of Fitle's five INCOHERERANCE_WARNING_* keys. On every classic answer (empty when none is flagged); a flag never blocks the size. Classic recos now use the request's references (S05.04): they adjust predicted zones within a cap and change only the size.
    • Reco answer contract version 2 (T04.04.03, D89): size_conversions is Fitle's per-size shape {M: {FR: {size_name: "38"}, UK: {size_name: "10"}}} for every chart size (primary system left out, at most 3 other systems, the shop_country's system first), present for every status. v1's {EU: "M", FR: "38"} is gone.
    • POST /v1/reco/usual_size answers (T05.06.03): the §8 answer with mode: usual_size and Fitle's found, name, size_order, precision, plus is_usual_size, offset_applied, sizing_adjustment. fit_feeling is narrow|perfect|comfy, desired_fit slim|regular|oversize, size_system_id is optional and a sent sizing_adjustment is ignored (D89). No more 501 for this path.
    • Reco requests take auto (boolean, T05.08.01): the silent page-load reco; an incomplete profile with auto: true answers needs_measurements instead of 422.
    • Added GET /v2/sizes[?language=] (T04.04.01): the size system catalogue {items: [{id, code, name, scope, gender, body_part, country_codes}]}, 13 clothing systems and the shoe scales, EU id 2 (D89); any origin, CDN 5 min, no write route (405).
    • plugin_info: usual_size_list, usual_size_system_name and preferred_size_system_id are filled in usual-size mode (T05.06.01) and stay [], null, null otherwise.
    • Body (S14.10): the fit report has gapsCm (measured − requested for locked measure-only dimensions: hipsMax, inseam, torsoHeight; D90). GET /v1/body/schema's ETag also names a digest of the vocabulary, so a vocabulary change under the same model version is a new ETag; inseam is now advanced and torsoHeight is in the body group.

21. 2026-10-26 4edcedabc0f5

    • Added the body routes of S14.03: GET /v1/body/schema (vocabulary + model version, any origin, ETag per model version), POST /v1/body/fit (202 + job; Idempotency-Key header, 409 for a reused key with another body, 429 per device, per client and at 100 queued fits), GET / DELETE /v1/body/jobs/{id} (states queued|running|done|failed|cancelled, retryAfterMs, 410 after 24 h, another client's job 404), GET /v1/body/results/{file} (<id>.glb with morphs=1, .json fit report, .obj; the MTL routes are gone) and GET /v2/body/morph_basis (302 to the model version, then an immutable GLB, any origin; T14.04.02).
    • Body routes list their error answers (400/422, 403, 404, 410, 429, 503) with an example each; GLB and OBJ answers are documented as binary. Predict and default are unchanged.

22. 2026-10-26 c867a71f6c6c

    • Added GET /v1/plugins/origin_check?client_id=&origin= (T13.03.01): the widget iframe asks whether the page that framed it is an allowed domain of the client, before it posts anything to it. Answers {allowed}; never cached; a refused origin gets {allowed:false, reason:"not_whitelisted"} (D39).

23. 2026-10-26 cca02bee590b

    • Added the reco routes with Fitle's paths (S05.01): POST /v3/reco/clothes (the CONTRACTS §8 answer: Fitle's comfort[], sizing_chart_info, user_measurements, size_conversions, then ours), and POST /v1/reco/shoes, /v1/reco/head, /v1/reco/social_proof, /v1/reco/usual_size (body checked, then 501 mode_not_available until S05.05–S05.07). Request examples per mode. New error codes: product_not_eligible (404, with reason), mode_not_available (501). A route called with another method answers 405 with Allow.

24. 2026-10-23 a717d7b9dd8a

    • Added POST /v1/body/predict?client_id=[&tracking_id=] (T14.02.04): Simple-mode answers → every body measurement with its own sd (predicted / entered), the live body's morphParams, modelVersion, predictorVersion, accuracyValidated:false; boys and girls get needs_measurements. Rate limited per device.
    • Added GET /v1/body/default?bodyType=[&modelVersion=] (T14.01.03): 302 to the current model version, then the default body as a public, immutable artifact.
    • New error codes validation_failed (422, with error.fields: names only) and predictor_not_available (501).

25. 2026-10-23 318ac4d1b0d3

    • POST /events and POST /events/pixel/shopify answer 202 {received, accepted, rejected} once the call is queued (S08.02, D72); POST /events also takes {events:[…]}. Added POST /debug (integration heartbeats, same forms and answer). New error codes: unknown_client, unknown_event, event_id_conflict (409), queue_unavailable (503).

26. 2026-10-23 caee300a758d

    • Added GET /v2/sizing_charts/{id_or_slug}?client_id=[&system=] (S04.01 T04.01.03): the published version of a size chart in the widget payload shape (measurements[] with =, or >/< constraints and the size label per system), plus id, version, revision, basis, sizes and ease_cm. Cached 5 minutes at the CDN.

27. 2026-10-22 3e355978abc5

    • PUT /wrong_sizing_chart_products: the body may carry up to 200 page_sizes (was 100), matching the SDK (T06.03.02-TC20).

28. 2026-10-22 8e992ceb6d10

    • PUT /wrong_sizing_chart_products: description and client_product_id text reworded (no behaviour change).

29. 2026-10-22 d9601bd3dfc8

    • Added GET /v1/products/plugin_info?client_id=&client_product_id=[&available_sizes=] (Fitle's path, S06.03 T06.03.01): the eligible answer (the D19-compatible keys, then ours; each field's description starts with D19 compatible: or Added:), the not-eligible answer {eligible:false, reason} (D50) and the soft refusal (D39).

30. 2026-10-22 7ba02b42c08f

    • Added PUT /wrong_sizing_chart_products?client_id=&client_product_id= (Fitle's path, S03.09 T03.09.03) with the optional body {page_sizes, status}. A request body that may be left out is no longer marked required.

31. 2026-10-22 5db0a5a18bd8

    • First generated reference: GET /v1/brands/{brand_id}/client, GET /v2/plugins/customization, POST /events, POST /events/pixel/shopify, GET /v1/api_keys/me (D19 paths), with the shared error answers (400, 401, 403, 404, 413, 429, 503).

Event catalogue

Changes to the events you send, by catalogue version. See Event schemas.