--- title: Product Recommendations API reference description: Learn about the requests that the Product Recommendations API can make and the responses it will return. api_name: ajax source_url: html: https://shopify.dev/docs/api/ajax/reference/product-recommendations md: https://shopify.dev/docs/api/ajax/reference/product-recommendations.md --- ExpandOn this page * [GET /{locale}/recommendations/products.​json](https://shopify.dev/docs/api/ajax/reference/product-recommendations#get--locale-recommendations-productsjson) * [GET /{locale}/recommendations/products](https://shopify.dev/docs/api/ajax/reference/product-recommendations#get--locale-recommendations-products) * [Tracking conversions for product recommendations](https://shopify.dev/docs/api/ajax/reference/product-recommendations#tracking-conversions-for-product-recommendations) # Product Recommendations API reference The Product Recommendations API can be used to recommend related products for a given product. To learn more about how recommendations are made and the associated limitations, refer to [Product recommendations](https://shopify.dev/docs/storefronts/themes/product-merchandising/recommendations). To learn how to show product recommendations in your theme, refer to [Product recommendations](https://shopify.dev/docs/storefronts/themes/product-merchandising/recommendations). All Ajax API requests should use [locale-aware URLs](https://shopify.dev/docs/api/ajax#locale-aware-urls) to give visitors a consistent experience. Note The [Shopify Search & Discovery app](https://apps.shopify.com/search-and-discovery) enables users to customize product recommendation and search results, which can impact results from [storefront search](https://shopify.dev/docs/storefronts/themes/navigation-search/search) and the Ajax Product Recommendations API. To learn about how these results can be impacted, visit the [Shopify Help Center](https://help.shopify.com/manual/online-store/search-and-discovery/product-recommendations). *** ## GET /{locale}/recommendations/products.​json The following example request retrieves the recommended products for a specific product: ```js GET /{locale}/recommendations/products.json?product_id={product-id}&intent={intent} ``` ### Query parameters | Query parameter | Required | Description | | - | - | - | | `product_id` | Yes | The unique [product ID](https://shopify.dev/docs/api/liquid/objects/product#product-id) of the product that you want to show recommended products for. | | `limit` | No | Limits the number of results.The value can range from `1` to `10`, and the default is `10`. | | `intent` | No | The recommendation intent that is used to generate product recommendations. You can use `intent` to generate product recommendations on various pages across the online store, according to different strategies. [Learn more about recommendation intents](https://shopify.dev/docs/storefronts/themes/product-merchandising/recommendations).The accepted values are `related` and `complementary`. The default value is `related`. | ## Example request object ```json { "product_id": "1234567890123", "limit": 4, "intent": "related" } ``` ## Example request using Fetch ```js fetch(window.Shopify.routes.root + "recommendations/products.json?product_id=1234567890123&limit=4&intent=related") .then(response => response.json()) .then(({ products }) => { if (products.length > 0) { const firstRecommendedProduct = products[0]; alert( `The title of the first recommended product is: ${firstRecommendedProduct.title}` ); } } ); ``` ### Products response The following example is a response to a successful request to the `/{locale}/recommendations/products.json` endpoint: ## Example product response ```json { "intent": "related", "products": [ { "id": 35, "title": "Gorgeous Silk Coat", "handle": "gorgeous-silk-coat", "description": null, "published_at": "2019-02-26T11:34:58-05:00", "created_at": "2019-02-26T11:34:58-05:00", "vendor": "Marge Group", "type": "Outdoors", "tags": [], "price": 380000, "price_min": 380000, "price_max": 790000, "available": true, "price_varies": true, "compare_at_price": null, "compare_at_price_min": 0, "compare_at_price_max": 0, "compare_at_price_varies": false, "variants": [ { "id": 69, "title": "Small Aluminum Knife", "option1": "Small Aluminum Knife", "option2": null, "option3": null, "sku": "", "requires_shipping": true, "taxable": true, "featured_image": null, "available": true, "name": "Gorgeous Silk Coat - Small Aluminum Knife", "public_title": "Small Aluminum Knife", ``` ### Error responses When a request to the `/{locale}/recommendations/products.json` endpoint is unsuccessful, one of the following error responses is returned: * [Invalid parameter](#invalid-parameter) * [Product not found](#product-not-found) #### Invalid parameter In the absence of a `product_id` parameter, the endpoint returns the following error: ```json { "status": 422, "message": "Invalid parameter error", "description": "A product_id value is missing" } ``` If `intent` isn't one of `related` or `complementary`, then the endpoint returns the following error: ```json { "status": 422, "message": "Invalid parameter error", "description": "The intent parameter must be one of related, complementary" } ``` #### Product not found If the `product_id` is for a product that doesn't exist, or that isn't published in the **Online store** channel, then the endpoint returns the following error: ```json { "status": 404, "message": "Product not found", "description": "No product with id is published in the online store" } ``` *** ## GET /{locale}/recommendations/products The following example request retrieves the HTML from a section rendered with product recommendations for a specific product. ```js GET /{locale}/recommendations/products?product_id={product-id}§ion_id=product-recommendations ``` ### Query parameters | Query parameter | Required | Description | | - | - | - | | `product_id` | Yes | The unique [product ID](https://shopify.dev/docs/api/liquid/objects/product#product-id) of the product that you want to show recommended products for. | | `limit` | No | Limits the number of results.The value can range from `1` to `10`, and the default is `10`. | | `section_id` | Yes | The unique [section ID](https://shopify.dev/docs/api/ajax/section-rendering#find-section-ids) of the section file that you want to render with product recommendations. | | `intent` | No | The recommendation intent that is used to generate product recommendations. You can use `intent` to generate product recommendations on various pages across the online store, according to different strategies. [Learn more about recommendation intents](https://shopify.dev/docs/storefronts/themes/product-merchandising/recommendations#recommendation-intents).The following values are accepted: `related`, `complementary`. The default value is `related`. | ## Example request object ```json { "product_id": "1234567890123", "limit": 4, "section_id": "product-recommendations", "intent": "related" } ``` ## Example request using Fetch ```js const productRecommendationsSection = document.querySelector('.product-recommendations'); fetch(window.Shopify.routes.root + "recommendations/products?product_id=12345690123&limit=4§ion_id=product-recommendations&intent=related") .then(response => response.text()) .then((text) => { const html = document.createElement('div'); html.innerHTML = text; const recommendations = html.querySelector('.product-recommendations'); if (recommendations && recommendations.innerHTML.trim().length) { productRecommendationsSection.innerHTML = recommendations.innerHTML; } }); ``` ### Section response The response to a successful request to the `/{locale}/recommendations/products` endpoint. The section response contains the HTML of the provided section rendered with the [`recommendations` object](https://shopify.dev/docs/api/liquid/objects/recommendations) containing the recommended products for the specified product. For example, the following section would generate the following section response: ## Example section ```liquid {%- if recommendations.performed? -%}
{%- if recommendations.products_count > 0 -%} {% if recommendations.intent == 'related' %}

You may also like

{% elsif recommendations.intent == 'complementary' %}

Pair it with

{% endif %} {%- endif -%}
{%- endif -%} ``` ## Example section response ```html

You may also like

``` ### Error responses When a request to the `/{locale}/recommendations/products` endpoint is unsuccessful, one of the following error status codes is returned: | Status code | Description | | - | - | | `404` | * **Product not found** - The provided product ID doesn't exist, or doesn't belong to a product published on the **Online store** channel. * **Section not found** - The provided section ID wasn't found in the theme. | | `422` | - **Invalid parameter error** - The `product_id` query parameter was missing. - **Invalid parameter error** - The `intent` parameter must be one of `related`, `complementary`. | *** ## Tracking conversions for product recommendations The `url` property for each `product` in the [products response](#products-response) contains URL parameters that lets you build a conversion funnel that can be tracked by using reports in Shopify. Similarly, the Liquid `url` property returned for [`recommendations.products`](https://shopify.dev/docs/api/liquid/objects/recommendations#recommendations-products) contains this tracking information as well. The URL uses the following format: ```text /products/gorgeous-wooden-computer?pr_choice=default&pr_prod_strat=description&pr_rec_pid=13&pr_ref_pid=17&pr_seq=alternating ``` To learn more about product recommendation reports, see [Product recommendation conversion over time](https://help.shopify.com/manual/reports-and-analytics/shopify-reports/report-types/behaviour-reports#product-recommendation-conversions-over-time). *** * [GET /{locale}/recommendations/products.​json](https://shopify.dev/docs/api/ajax/reference/product-recommendations#get--locale-recommendations-productsjson) * [GET /{locale}/recommendations/products](https://shopify.dev/docs/api/ajax/reference/product-recommendations#get--locale-recommendations-products) * [Tracking conversions for product recommendations](https://shopify.dev/docs/api/ajax/reference/product-recommendations#tracking-conversions-for-product-recommendations)