# 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](https://docs.parcellab.com/docs/developers/size-recommender/size-recommender/ui-plugin) 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.