Recommendations API

Use POST /recommendations to rank products from a Shopify or Custom JavaScript catalog. Call this endpoint from a trusted backend with your virtual.fit API key.

Never expose your API key in browser JavaScript, a theme file, or a mobile application.

Send requests to https://api.virtual.fit.

Request

Custom JavaScript
Shopify

curl --request POST \
  "https://api.virtual.fit/recommendations" \
  --header "Authorization: Bearer $VIRTUAL_FIT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "site_key": "site_pub_your_key",
    "intent": "complete_the_look",
    "product_ids": ["linen-shirt", "tailored-trousers"],
    "cart_product_ids": ["canvas-tote"],
    "exclude_product_ids": ["sold-out-belt"],
    "shopper_id": "anon-session-7f19b2",
    "limit": 8,
    "surface": "outfit_builder"
  }'

curl --request POST \
  "https://api.virtual.fit/recommendations" \
  --header "Authorization: Bearer $VIRTUAL_FIT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "shop_domain": "your-store.myshopify.com",
    "intent": "similar",
    "product_ids": ["gid://shopify/Product/9876543210"],
    "shopper_id": "customer-48291",
    "limit": 8,
    "surface": "product_page"
  }'

Body fields

Field	Required	Description
`site_key`	For Custom JavaScript	The public site key owned by the API-key account.
`shop_domain`	For Shopify	The store’s canonical `.myshopify.com` domain.
`intent`	Yes	`similar`, `complete_the_look`, or `likely_purchases`. See Intent semantics.
`product_ids`	By intent	Exactly one ID for `similar`; one to five outfit products for `complete_the_look`; optional current or selected products for `likely_purchases`. For `complete_the_look`, put the primary outfit item first.
`cart_product_ids`	For a live cart	The latest full cart, up to 500 product IDs. Required for cart-only `likely_purchases` requests. Cart items are excluded from results and influence multi-item ranking, but do not occupy outfit categories.
`candidate_product_ids`	No	Restrict ranking to a non-empty array of at most 10,000 product IDs. Useful when your backend has already applied availability, market, or collection filters.
`exclude_product_ids`	No	Up to 500 product IDs that must not appear. Use this as an explicit availability or merchandising override. Context products are excluded automatically.
`shopper_id`	Recommended for shopper-facing requests	Your stable, opaque customer or anonymous-session identifier. virtual.fit uses it only to keep one shopper from consuming the store’s shared request allowance. Do not send an email address or other directly identifying value.
`limit`	No	Maximum results. Defaults to `12` and is capped at `100`.
`surface`	No	Your placement label, such as `product_page`, `cart`, or `fitting_room`.

Use the same stable IDs that you send during catalog sync and commerce tracking. For Shopify, send the full GraphQL product ID, such as gid://shopify/Product/9876543210. Unknown or disabled candidate IDs are ignored. If candidate_product_ids is present, it must be an array containing at least one ID, and at least one supplied ID must resolve to an enabled product; otherwise the request fails with 400. Omitting the field leaves ranking open to the enabled catalog. A request fails when none of its ranking context is prepared. The JSON body is limited to 1 MiB. Each product ID and shopper_id is limited to 256 UTF-8 bytes. Requests over a body, identifier, or array limit fail with 413.

Response

{
  "items": [
    {
      "product_id": "leather-loafer",
      "target_type": "variant",
      "variant_id": "black-42",
      "recommended_option_values": {
        "color": "Black",
        "size": "42"
      },
      "rank": 1,
      "score": 1.274,
      "title": "Leather Loafer",
      "handle": "leather-loafer",
      "canonical_url": "https://shop.example/products/leather-loafer?variant=black-42",
      "image_url": "https://cdn.example.com/leather-loafer-black.jpg",
      "variant_title": "Black / 42",
      "price": "129.0000",
      "compare_at_price": "159.0000",
      "currency": "USD",
      "available": true,
      "fit_evidence": {
        "review_count": 128,
        "analyzed_review_count": 42,
        "average_rating": 4.7,
        "signals": [
          {
            "dimension_code": "overall",
            "evidence_count": 34,
            "average_score": 0.03,
            "tight_count": 5,
            "neutral_count": 25,
            "loose_count": 4
          }
        ]
      }
    }
  ],
  "unknown_context_ids": []
}

rank defines the display order. score is optional and meaningful only within that response. Do not re-sort items by score or compare scores across requests. Each item includes the selected target plus the product fields needed for a card. It deliberately omits full galleries, sibling variants, and complete option matrices.

Field	Meaning
`target_type`	`variant` for one exact purchasable choice, `visual_group` for a best color/style without choosing every purchase option, or `product` when no narrower target is available.
`variant_id`	Stable source variant ID when `target_type` is `variant`; otherwise `null`.
`recommended_option_values`	The selected color/style and, for an exact variant, its full option selection. Apply these values before falling back to storefront defaults.
`canonical_url`	Exact variant URL when available, otherwise the product URL.
`image_url`	One prepared display image for the selected target.
`price`, `compare_at_price`, `currency`	Selected variant pricing with product pricing as the fallback. Amounts are decimal strings.
`available`	`true` when current availability is known; `null` when the source does not provide reliable inventory. Known-unavailable targets are omitted.
`fit_evidence`	Optional compact rating and fit summary. `review_count` is the source aggregate; `analyzed_review_count` is the number of full reviews available for fit analysis. Full review text and media are not included in recommendation cards.

virtual.fit returns at most one item per product. A visually best color can be returned as visual_group without inventing a size; an exact in-stock variant can be returned as variant. unknown_context_ids contains supplied context IDs that are not prepared in the selected catalog. The request can still succeed when at least one other context product is available.

Same-category recommendations

Send exactly one context product:

{
  "site_key": "site_pub_your_key",
  "intent": "similar",
  "product_ids": ["linen-shorts"],
  "limit": 12
}

You may also send candidate_product_ids when your backend has a more specific constraint, such as an in-stock collection or shopper market. You do not need to send a category. virtual.fit categorizes prepared products automatically. Keep Custom JavaScript product titles and images current so similar can return relevant alternatives. Recommendation eligibility is broader than try-on eligibility. Apparel accessories such as shoes, bags, and jewellery can appear in recommendation results even when they are not supported as virtual try-on items.

Intent semantics

`complete_the_look`

The hosted fitting room uses this intent automatically. Call it directly for another outfit placement or your own outfit builder. It excludes categories already represented by known context products. If no eligible compatible product remains, items can be empty. Treat that as a valid result instead of widening it to unrelated products. Send one to five products already selected for the outfit. Send the current cart separately when it should also influence relevance:

{
  "site_key": "site_pub_your_key",
  "intent": "complete_the_look",
  "product_ids": [
    "linen-shirt",
    "tailored-trousers",
    "suede-jacket"
  ],
  "cart_product_ids": ["canvas-tote"],
  "limit": 8
}

Only product_ids determines which outfit categories are already occupied. cart_product_ids improves the ranking and is excluded from results, but a bag sitting in the cart does not prevent the outfit builder from recommending another bag.

`likely_purchases`

Use this for “You may also like,” cart, post-add-to-cart, and general cross-sell placements. It uses the same current-product context and learned purchase behavior, but it does not remove categories already represented in that context:

{
  "site_key": "site_pub_your_key",
  "intent": "likely_purchases",
  "cart_product_ids": ["linen-shirt", "tailored-trousers"],
  "limit": 8,
  "surface": "cart"
}

likely_purchases accepts a current product, selected products, a cart, or any combination of them. All supplied products are excluded automatically. Your backend must send the latest full cart in cart_product_ids; it affects that request immediately. Synced cart and purchase events can improve recommendations over time.

Error handling

Rate limits

The recommendations API uses short-term safety thresholds of 60 requests per shopper per minute and 6,000 requests per store per minute. Treat these values as usage guidance rather than exact quotas, and always handle 429 responses. Send shopper_id on shopper-facing backend requests. Different shoppers then use separate allowances even when every request leaves your infrastructure through the same IP address. Authenticated requests are not limited by the merchant backend’s shared egress IP. The hosted Shopify and Custom JavaScript browser integrations supply shopper identity automatically. Direct browser requests also use a short-term safety threshold of 600 requests per IP per minute. Treat it as usage guidance and handle 429 responses. Rate-limited requests return 429 with Retry-After and retry_after_seconds. Wait for that duration before retrying. Keep your existing merchandising order visible while waiting.

Status	Meaning
`400`	The integration selector, intent, product count, or supplied candidate set is invalid.
`401`	The API key is missing or invalid.
`413`	The JSON body, a product-ID array, a product ID, or `shopper_id` exceeds its documented limit.
`429`	The shopper, store, or public client IP exceeded a short-term safety limit. Wait for the `Retry-After` duration before retrying.
`404`	The requested storefront is missing or inaccessible, or none of the context products are prepared.
`503`	Recommendations are temporarily unavailable. Retry with backoff or use your existing fallback order.

Keep your current merchandising order as a fallback. A temporary recommendation failure should not hide eligible products or block checkout.

Get started

Shopify

Custom JavaScript