How to Add Size Recommendations With an API

Most size recommendation vendors sell you a widget, not an API. If your storefront is custom-built — a headless commerce frontend, a native app, or a checkout flow that doesn't tolerate a bolted-on iframe — that's a problem. This post walks through the integration shape that actually works: what to send, when to call it, how to cache it, and what to do when it fails.

Why API-First Matters for Custom Storefronts

A drop-in widget assumes a DOM you don't control and a rendering cadence you don't own. Headless storefronts built on Next.js, Remix, or a native mobile shell need the recommendation logic to live inside their own component tree — which means a JSON contract, not a script tag.

The practical difference shows up in three places: latency budget, state ownership, and design consistency. An API call you make yourself can be parallelized with other product-page data fetches, cached at the edge, and styled with your own component library instead of an injected iframe. This is the same reasoning that pushes teams toward shopify integration patterns that use native app blocks rather than embedded frames — control over rendering is worth the extra integration work.

Request and Response Shape

A size recommendation API call typically needs three ingredients: a product identifier (with its size chart or garment metadata), a shopper's stored or session measurements, and a locale/unit preference. A minimal request body looks like this:

{
  "productId": "sku_48213",
  "measurements": {
    "heightCm": 172,
    "weightKg": 64,
    "fitPreference": "regular"
  },
  "unit": "metric"
}

The response should return a ranked recommendation, not just a single guess — confidence scores let the frontend decide whether to show one size prominently or present two options with a note. A reasonable shape:

{
  "recommended": "M",
  "alternatives": [
    { "size": "L", "confidence": 0.31 }
  ],
  "confidence": 0.87,
  "fallback": false
}

Design the contract so confidence and fallback are always present — your frontend logic branches on both, and a missing field shouldn't cause a silent crash on checkout.

When to Call the Endpoint

Calling on every page load wastes a round trip; calling only on an explicit "find my size" click adds friction shoppers won't take. The middle ground that works best in practice: call once when the product page mounts if a shopper profile already exists (returning visitor, logged-in account, or a saved session), and call again only when the shopper changes measurements or switches products.

For product listing pages, don't call the recommendation endpoint per card — batch it. A single request with an array of productId values returns recommendations for the whole grid in one round trip, which matters more than it sounds on mobile connections.

Caching Strategy

Size recommendations are cacheable but not infinitely so — a shopper's measurements rarely change within a session, but garment metadata (a size chart correction, a new fit note) can change server-side at any time. A workable policy:

Caching at the edge on productId alone (excluding shopper-specific measurements) works if your recommendation model is deterministic given inputs — cache the computation, not the shopper's identity. If your endpoint blends in real-time signals like recent return history, keep TTLs short and treat the cache as a latency buffer, not a source of truth.

Privacy and Data Handling

Body measurements are sensitive by any reasonable definition, even when a shopper enters them voluntarily to get a better fit. Store the minimum needed — height, weight, and fit preference are usually sufficient; you rarely need to persist raw survey answers or device sensor data. Give shoppers a visible way to clear stored measurements, and don't pass them to third-party analytics or ad pixels by default.

This is a topic worth treating as first-class API design, not an afterthought bolted on before a privacy review. Our related piece on body data privacy in try-on covers the specific expectations shoppers have when a brand asks for body measurements, which is useful reading before you finalize your request schema.

Graceful Fallbacks When the API Fails or Has No Data

An API call can fail for ordinary reasons — a timeout, a cold cache, or a shopper with no measurement history yet. The response contract above includes a fallback: true flag for exactly this case; your frontend should treat it as "no confident recommendation" rather than an error state.

Sensible fallback behavior, in order of preference:

• If a static size chart exists for the product, render it instead of a blank recommendation slot.
• If the shopper has no measurements at all, prompt for a quick 2-field entry (height and one fit preference) rather than a long form.
• If the API times out, don't block the add-to-cart button — degrade to the size chart silently and log the failure for monitoring.

Never let a failed recommendation call become a failed page load. This mirrors the general SEO-adjacent principle from how to read a size chart correctly: a size chart is not a failure mode, it's the baseline every recommendation system should be able to fall back to.

Handling Multi-Brand and Multi-Size-System Complexity

If your storefront spans multiple brands or vendors, don't assume one size chart schema fits all. Brands routinely label the same garment differently — a US 8 from one label can fit like a US 6 from another, which is well documented in the industry and is one of the harder integration problems for custom builds. Your API layer should carry a brandId or vendorId alongside productId so the recommendation engine can apply brand-specific fit models rather than a single global curve.

This complexity is also why size charts alone are a weak substitute for computed recommendations at scale — a chart tells a shopper what a brand claims, not how the garment actually fits relative to a body. For more on this distinction, see size chart vs size recommendation.

Where YourSizer Fits

YourSizer's recommendation engine is available as a direct API, not only as a packaged widget, specifically for teams building custom storefronts or native apps. The request/response contract follows the shape described above: a product and shopper profile in, a ranked size with a confidence score out, with an explicit fallback flag so your frontend never has to guess whether a response is authoritative.

Measurement data is handled with retention limits and clear deletion paths, and the API supports batched requests for listing pages so you're not making one round trip per product card. Integration teams typically wire it into an existing product-data fetch layer — Next.js server components, a GraphQL resolver, or a native app's product service — rather than adding a separate client-side script, which keeps latency and design control in your hands.

Frequently Asked Questions

Does the size recommendation API need real-time measurements, or can it use stored profile data?

Either works, and most integrations use both. A returning shopper's stored profile (height, weight, fit preference) is the primary input, while a first-time visitor typically enters a quick two-field estimate that gets cached to their session. The API should accept both paths through the same measurements object so your frontend doesn't need separate code branches for new versus returning shoppers.

How is this different from just embedding a size recommendation widget?

A widget owns its own rendering, styling, and often its own iframe boundary, which is fast to integrate but limits control over layout and page performance. An API-first integration means your team owns the UI entirely and only consumes the recommendation logic as data, which is the right tradeoff for headless storefronts, native apps, or brands with strict design systems where an embedded frame doesn't fit.

What should happen if the API returns a low-confidence recommendation?

Treat a low confidence score as a signal to show alternatives rather than commit to one size. A reasonable frontend pattern is to display the top recommendation prominently when confidence is above roughly 0.7-0.8, and to show two sizes side by side with a short note when it falls below that. This keeps the shopper informed without forcing a false sense of certainty into the UI, which is one of the areas covered in how to choose a size recommendation solution.

Can the API support multiple brands with different size systems in one storefront?

Yes, as long as the request includes a brand or vendor identifier alongside the product ID, since fit models need to be brand-aware rather than global. Marketplaces and multi-brand retailers are the most common case where this matters — a single "size M" label means different things across vendors, and a well-designed API accounts for that instead of averaging it away.

Conclusion

Building size recommendations into a custom storefront is mostly an integration design problem, not a machine learning one — the hard parts are the contract shape, the caching boundaries, and what happens when the call fails. Get those right and the recommendation layer becomes just another data dependency your frontend handles gracefully, the same way it already handles inventory or pricing APIs. As more commerce moves to headless and native architectures, API-first fit tooling is likely to become the default expectation rather than the exception.