# Size Recommender API

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](/docs/developers/size-recommender/size-recommender/ui-plugin.md) or to build your own custom integration.

{% hint style="info" %}
For the full OpenAPI specification, see the [Size Recommender API Reference](https://api.parcellab.com/v4/docs/#tag/Size-Recommender).
{% endhint %}

## 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

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

### Example response

```json
{
  "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.                                                                                                          |

{% hint style="warning" %}
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.
{% endhint %}

## 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.parcellab.com/docs/developers/size-recommender/size-recommender/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.