Size Recommender API

REST API for retrieving AI-powered size recommendations including fit category, confidence score, and customer feedback summary.

The Size Recommender API returns fit guidance for a specific product based on aggregated return data and customer feedback. Use this endpoint to power the Selection Guide UI widget or to build your own custom integration.

For the full OpenAPI specification, see the Size Recommender API Reference.

Endpoint

GET /v4/size-recommender/recommendation/{productId}/

Base URL: https://api.parcellab.com

Path parameters

Parameter	Type	Description
productId	string	The product identifier. This should match the product name or ID used in your order data. URL-encode if it contains special characters.

Query parameters

Parameter	Type	Required	Description
account_id	integer	Yes	Your parcelLab account ID.

Example request

curl "https://api.parcellab.com/v4/size-recommender/recommendation/Men's%20Iver%20Pants%20(tailored%20fit)/?account_id=1617954"

Example response

{
  "article_name": "Men's Iver Pants (tailored fit)",
  "size_fit_category": "Likely to run small",
  "confidence_smetabase_core": 0.996,
  "smoothed_fit_position": -0.538,
  "raw_fit_position": -0.636,
  "n_outbound": 292,
  "llm_summary": "The Men's Iver Pants in tailored fit may run small, particularly in the waist, as some customers have noted that the waistband feels tighter than expected. If you're considering these pants, you might want to size up for a more comfortable fit.",
  "account_id": 1617954
}

Response fields

Field	Type	Description
article_name	string	The product identifier as stored in parcelLab.
size_fit_category	string | null	Human-readable fit label, e.g., "Likely to run small", "True to size", or "Likely to run large". null if insufficient data.
confidence_smetabase_core	number	Confidence score between 0 and 1. Higher values indicate more reliable recommendations.
smoothed_fit_position	number	Normalized fit position on a scale from -1 (runs very small) to +1 (runs very large). 0 indicates true to size. This value is smoothed for display purposes.
raw_fit_position	number	Raw (unsmoothed) fit position. Useful for analytics or custom visualizations.
n_outbound	integer	Total number of outbound shipments analyzed for this product.
llm_summary	string	AI-generated plain-language summary of customer feedback about the product's fit.
account_id	integer	The account ID associated with this recommendation.

Some response fields like article_image_url, problem_descriptions, small_returns, big_returns, total_returns, and article_return_rate are also returned but are intended for internal use. The UI widget does not display these fields.

Error handling

HTTP Status	Meaning	Recommended action
200	Recommendation found.	Display the recommendation.
404	No recommendation available for this product.	Show a fallback or hide the widget. The UI widget handles this automatically via notFoundMode with true-to-size, empty, or hidden.
429	Rate limited.	Retry after the delay indicated in the response headers.
5xx	Server error.	Retry with exponential backoff.

Caching

The UI widget caches responses by accountId + productId combination for the duration of the page session. If you build a custom integration, consider caching responses to avoid unnecessary API calls — recommendation data changes infrequently (typically updated daily).

Authentication

The Size Recommender API is a public, read-only endpoint. No authentication token is required. The account_id query parameter scopes the request to your account's data.