API reference

Sizing, product lookup and webhooks for apps and headless stores. Everything under /v1 keeps its shape; breaking changes would come as /v2. Responses carry X-Request-Id; errors are { error, code, requestId }.

Base URLhttps://api.fitld.com/v1

OpenAPI 3.1 document

Authentication

Storefront calls send your public widget ID (wgt_…) in the body: it's safe in page HTML. Server calls send your secret key in the x-api-key header; a secret key sent from a browser on a store is refused, so it's useless to anyone who copies it from a page. Both are under Settings in your dashboard.

Errors

Every response has an X-Request-Id header. Errors also return it in the body, with a message you can show (error) and a stable reason for your code (code). Messages may be reworded; codes never are. Each endpoint below lists its codes.

errorstringrequired: A message you can show. May be reworded.
codestringrequired: Stable reason, for your code. Never reworded.
requestIdstringrequired: Quote it to FITLD support; same as the X-Request-Id header.
missingstring[]: With measurements_missing: the measurements to ask for.
detectedobject: With product_not_connected: what FITLD read from the page.
connectHintobject: With product_not_connected: a suggested store handle.
upgradeUrlstring
livemodefalse

Test mode

use your test widget ID (wgt_test_…) or test key (fit_sk_test_…) to get real sizes with nothing recorded or billed, up to 1000 requests a day. Test responses carry "livemode": false.

post/v1/widget/recommend

What the FITLD widget calls. Authenticated by the public widget ID in the body, so it can be called from any store page. Send measurements, or a signed-in shopper's userId + userToken (and optionally dependentId for a family member). Counts as one recommendation.

Authentication · Widget ID in the body.

Request body

widgetIdstringrequired: Your widget ID (wgt_…), or the test one (wgt_test_…).
productIdstringrequired
measurementsMeasurements: A shopper's body measurements. Send what you have: FITLD asks only for what this product's chart needs, and answers 422 measurements_missing with the list when something essential is missing.
userIdstring: Signed-in shopper (from the widget's FITLD sign-in).
userTokenstring
dependentIdstring: A family member on the shopper's profile.
sessionIdstring: The shopper's browsing session; links the size to the order later.

Responses

200: The size.
400: Missing widget ID, product ID or measurements.
invalid_request, product_id_required, invalid_measurement, invalid_json
401: The shopper's sign-in expired.
authentication_required
404: Unknown widget, product or family member.
not_found, product_not_found
422: FITLD can't size this request.
measurements_missing, category_not_supported, chart_not_usable, size_not_determined
429: Too many requests, the plan's ceiling, or the test-mode daily allowance. Wait for Retry-After.
rate_limited, quota_exceeded, test_mode_limit

curl https://api.fitld.com/v1/widget/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "widgetId": "wgt_YOUR_WIDGET_ID",
    "productId": "OXFORD-SHIRT",
    "measurements": {
      "unit": "cm",
      "height": 178,
      "chest": 98,
      "waist": 84
    },
    "sessionId": "s_2f9c1a"
  }'

200 Response

{
  "recommended_size": "M",
  "out_of_range": null,
  "confidence": 0.91,
  "fit_quality": "great",
  "measurement_gap_cm": 1.2,
  "category": "Tops",
  "tolerance": 4,
  "explain": {
    "between_sizes": null,
    "alternatives": [
      {
        "size": "L",
        "score": 6.4
      },
      {
        "size": "S",
        "score": 7.9
      }
    ],
    "comparisons": [
      {
        "field": "chest",
        "you": 98,
        "size": 100,
        "unit": "cm"
      },
      {
        "field": "waist",
        "you": 84,
        "size": 86,
        "unit": "cm"
      }
    ],
    "why": [
      "Closest overall match (avg gap 1.2 cm)",
      "For Tops",
      "Age group: Adult"
    ]
  },
  "size_system": null,
  "equivalents": null,
  "chart": "product",
  "guest": true
}

422 Error

{
  "error": "Your measurements are missing: chest. Please add the missing measurement.",
  "code": "measurements_missing",
  "missing": [
    "chest"
  ],
  "requestId": "req_8fK2xQm1Lw0aZt7c"
}

post/v1/products/resolve

Find the product on a page

Matches a product page to a FITLD product by product ID, SKU, external ID, store handle or URL. Authenticated by the widget ID in the body, or a secret key in x-api-key. Doesn't count as a recommendation.

Authentication · Widget ID in the body, or your secret key in x-api-key.

Request body

widgetIdstring: Required unless you send x-api-key.
productIdstring
externalProductIdstring
skustring
canonicalUrlstring
ogUrlstring
pageUrlstring
titlestring

Responses

200: The product.
400: No product ID or URL to go on.
invalid_request, invalid_json
401: No widget ID or API key, or an unknown one.
authentication_required
403: A secret key sent from a browser, or a test key on a non-public endpoint.
api_key_browser_origin, test_key_not_allowed
404: The page isn't connected to a FITLD size chart yet.
product_not_connected
429: Too many requests, the plan's ceiling, or the test-mode daily allowance. Wait for Retry-After.
rate_limited, quota_exceeded, test_mode_limit

curl https://api.fitld.com/v1/products/resolve \
  -H "x-api-key: $FITLD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "widgetId": "wgt_YOUR_WIDGET_ID",
    "canonicalUrl": "https://shop.example.com/products/classic-oxford"
  }'

200 Response

{
  "productId": "OXFORD-SHIRT",
  "productName": "Classic Oxford",
  "category": "Tops",
  "ageGroup": "Adult",
  "audience": "Men"
}

post/v1/recommend-size/guest

Server to server, with your secret key. Send the shopper's measurements. Counts as one recommendation.

Authentication · Your secret key in x-api-key.

Request body

productIdstringrequired
measurementsMeasurementsrequired: A shopper's body measurements. Send what you have: FITLD asks only for what this product's chart needs, and answers 422 measurements_missing with the list when something essential is missing.

Responses

200: The size.
400: Something in the request is missing or malformed.
product_id_required, invalid_measurement, invalid_json, invalid_request
401: No API key, or an invalid one.
authentication_required
403: A secret key sent from a browser, or a test key on a non-public endpoint.
api_key_browser_origin, test_key_not_allowed
404: No such product (or widget) for this brand.
product_not_found, not_found
422: FITLD can't size this request.
measurements_missing, category_not_supported, chart_not_usable, size_not_determined
429: Too many requests, the plan's ceiling, or the test-mode daily allowance. Wait for Retry-After.
rate_limited, quota_exceeded, test_mode_limit

curl https://api.fitld.com/v1/recommend-size/guest \
  -H "x-api-key: $FITLD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "OXFORD-SHIRT",
    "measurements": {
      "unit": "cm",
      "chest": 98,
      "waist": 84
    }
  }'

200 Response

{
  "recommended_size": "M",
  "out_of_range": null,
  "confidence": 0.91,
  "fit_quality": "great",
  "measurement_gap_cm": 1.2,
  "category": "Tops",
  "tolerance": 4,
  "explain": {
    "between_sizes": null,
    "alternatives": [
      {
        "size": "L",
        "score": 6.4
      },
      {
        "size": "S",
        "score": 7.9
      }
    ],
    "comparisons": [
      {
        "field": "chest",
        "you": 98,
        "size": 100,
        "unit": "cm"
      },
      {
        "field": "waist",
        "you": 84,
        "size": 86,
        "unit": "cm"
      }
    ],
    "why": [
      "Closest overall match (avg gap 1.2 cm)",
      "For Tops",
      "Age group: Adult"
    ]
  },
  "size_system": null,
  "equivalents": null,
  "chart": "product",
  "guest": true
}

422 Error

{
  "error": "Your measurements are missing: chest. Please add the missing measurement.",
  "code": "measurements_missing",
  "missing": [
    "chest"
  ],
  "requestId": "req_8fK2xQm1Lw0aZt7c"
}

post/v1/recommend-size

Server to server, with your secret key plus the shopper's FITLD sign-in token, for apps where the shopper signed in with FITLD. FITLD uses the measurements saved on their profile (or a family member's, with dependentId); your server never sees them.

Authentication · Your secret key in x-api-key, plus the shopper's token in Authorization: Bearer.

Request body

productIdstringrequired
dependentIdstring

Responses

200: The size.
400: Something in the request is missing or malformed.
product_id_required, invalid_measurement, invalid_json, invalid_request
401: No API key or shopper token, or an expired one.
authentication_required
403: A secret key sent from a browser, or a test key on a non-public endpoint.
api_key_browser_origin, test_key_not_allowed
404: Unknown product, shopper or family member.
product_not_found, not_found
422: FITLD can't size this request.
measurements_missing, category_not_supported, chart_not_usable, size_not_determined
429: Too many requests, the plan's ceiling, or the test-mode daily allowance. Wait for Retry-After.
rate_limited, quota_exceeded, test_mode_limit

curl https://api.fitld.com/v1/recommend-size \
  -H "x-api-key: $FITLD_SECRET_KEY" \
  -H "Authorization: Bearer $SHOPPER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "OXFORD-SHIRT"
  }'

200 Response

{
  "recommended_size": "M",
  "out_of_range": null,
  "confidence": 0.91,
  "fit_quality": "great",
  "measurement_gap_cm": 1.2,
  "category": "Tops",
  "tolerance": 4,
  "explain": {
    "between_sizes": null,
    "alternatives": [
      {
        "size": "L",
        "score": 6.4
      },
      {
        "size": "S",
        "score": 7.9
      }
    ],
    "comparisons": [
      {
        "field": "chest",
        "you": 98,
        "size": 100,
        "unit": "cm"
      },
      {
        "field": "waist",
        "you": 84,
        "size": 86,
        "unit": "cm"
      }
    ],
    "why": [
      "Closest overall match (avg gap 1.2 cm)",
      "For Tops",
      "Age group: Adult"
    ]
  },
  "size_system": null,
  "equivalents": null,
  "chart": "product"
}

422 Error

{
  "error": "Your measurements are missing: chest. Please add the missing measurement.",
  "code": "measurements_missing",
  "missing": [
    "chest"
  ],
  "requestId": "req_8fK2xQm1Lw0aZt7c"
}

get/v1/openapi.json

This document

The OpenAPI 3.1 description of the FITLD API. Import it into Postman, Insomnia or a client generator.

Authentication · None.

Responses

200: OpenAPI document.

curl https://api.fitld.com/v1/openapi.json

Webhook events

FITLD sends these to your endpoints (Settings → Webhooks) as signed POSTs, each wrapped in a WebhookEvent. Checking the signature, and retries, are explained in the docs.

Webhooks in the docs

order.attributed

An order includes items bought after using FITLD.

data

order_idstringrequired
order_namestring | null | null
currencystring | null | null
paid_atstring
linesWebhookLine[]required

refund.created

Items bought after using FITLD were refunded.

data

order_idstringrequired
refund_idstringrequired
refunded_atstring
linesobject[]required

return.recorded

A return of an item bought after using FITLD, with its reason.

data

order_idstringrequired
linesobject[]required

fit_feedback.received

A shopper said how an item fit.

data

order_idstring
product_idstring | null | null
product_namestring | null | null
sizestring | null | null
recommended_sizestring | null | null
followed_recommendationboolean | null | null
answer"too_small" | "right" | "too_large"

product.unmatched

A product page without a FITLD size chart was seen for the first time.

data

urlstring
titlestring | null | null
handlestring | null | null
first_seen_atstring

usage.threshold_reached

Recommendations this month reached 80% or 100% of your plan.

data

monthstring
thresholdnumber
usedinteger
limitinteger
planstring
hard_limitinteger

Measurements

A shopper's body measurements. Send what you have: FITLD asks only for what this product's chart needs, and answers 422 measurements_missing with the list when something essential is missing.

unit"cm" | "in": Unit of every length (and of weight: cm → kg, in → lb).
heightnumber: Height, in the chosen unit.
chestnumber: Chest / bust, in the chosen unit.
waistnumber: Waist, in the chosen unit.
hipsnumber: Hips, in the chosen unit.
shouldernumber: Shoulder width, in the chosen unit.
sleevenumber: Sleeve length, in the chosen unit.
bicepnumber: Bicep, in the chosen unit.
wristnumber: Wrist, in the chosen unit.
inseamnumber: Inseam, in the chosen unit.
outseamnumber: Outseam, in the chosen unit.
thighnumber: Thigh, in the chosen unit.
anklenumber: Ankle, in the chosen unit.
footLengthnumber: Foot length, in the chosen unit.
footWidthnumber: Foot width, in the chosen unit.
handLengthnumber: Hand length, in the chosen unit.
palmWidthnumber: Palm width, in the chosen unit.
necknumber: Neck, in the chosen unit.
headnumber: Head, in the chosen unit.
weightnumber: Weight: kg with cm, lb with in.
agenumber: Age (years).
ageMonthsnumber: Age (months).

Recommendation

recommended_sizestringrequired: The size to select, as written in the size chart.
out_of_rangeOutOfRange | nullrequired: Set when the shopper is outside every size: FITLD says so instead of guessing.
confidencenumberrequired: How closely the shopper matches the size (1 = exactly).
fit_quality"great" | "good" | "fair"required: confidence in words: ≥ 0.8 great, ≥ 0.5 good.
measurement_gap_cmnumberrequired: Average distance between the shopper and the size, in cm.
categorystringrequired
tolerancenumber: Distance (cm) still counted as a fit for this category.
explainobjectrequired
size_systemstring | null | null
equivalentsobject | null | null: The size in other systems, e.g. { "EU": "50" }.
chart"size_guide" | "product"required: Whether the answer used a shared size guide or the product's own chart.
guestboolean: True when sized from measurements in the request, not a signed-in profile.
variantstring: Experiment arm, when FITLD is testing a change (widget only).
livemodefalse: Only present, and false, for test-mode requests.

ResolvedProduct

productIdstringrequired: FITLD's id for the product; pass it to the sizing endpoints.
productNamestringrequired
categorystringrequired
ageGroupstringrequired: Which measurement form to show: Adult, Kids, Baby…
audiencestring | null | null
livemodefalse

Error

errorstringrequired: A message you can show. May be reworded.
codestringrequired: Stable reason, for your code. Never reworded.
requestIdstringrequired: Quote it to FITLD support; same as the X-Request-Id header.
missingstring[]: With measurements_missing: the measurements to ask for.
detectedobject: With product_not_connected: what FITLD read from the page.
connectHintobject: With product_not_connected: a suggested store handle.
upgradeUrlstring
livemodefalse

WebhookEvent

idstringrequired: Same on every retry: use it to ignore duplicates.
typestringrequired
createdstringrequired
livemodetruerequired
api_version"v1"required
dataobjectrequired

API reference

Authentication

Errors

Test mode

Recommend a size (storefront)

Request body

Responses

Find the product on a page

Request body

Responses

Recommend a size (server)

Request body

Responses

Recommend a size for a signed-in shopper

Request body

Responses

This document

Responses

Webhook events

data

data

data

data

data

data

Measurements

Recommendation

ResolvedProduct

Error

WebhookEvent