---
title: Product Recommendations API reference
description: >-
  Learn about the requests that the Product Recommendations API can make and the
  responses it will return.
source_url:
  html: 'https://shopify.dev/docs/api/ajax/reference/product-recommendations'
  md: 'https://shopify.dev/docs/api/ajax/reference/product-recommendations.md'
---

# 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",
         "options": [
           "Small Aluminum Knife"
         ],
         "price": 790000,
         "weight": 9500,
         "compare_at_price": null,
         "inventory_management": "shopify",
         "barcode": null
       },
       {
         "id": 70,
         "title": "Heavy Duty Bronze Shoes",
         "option1": "Heavy Duty Bronze Shoes",
         "option2": null,
         "option3": null,
         "sku": "",
         "requires_shipping": true,
         "taxable": true,
         "featured_image": null,
         "available": true,
         "name": "Gorgeous Silk Coat - Heavy Duty Bronze Shoes",
         "public_title": "Heavy Duty Bronze Shoes",
         "options": [
           "Heavy Duty Bronze Shoes"
         ],
         "price": 380000,
         "weight": 2200,
         "compare_at_price": null,
         "inventory_management": "shopify",
         "barcode": null
       }
     ],
     "images": [],
     "featured_image": null,
     "options": [
       {
         "name": "Color or something",
         "position": 1,
         "values": [
           "Small Aluminum Knife",
           "Heavy Duty Bronze Shoes"
         ]
       }
     ],
     "url": "/products/gorgeous-silk-coat?pr_choice=default&pr_prod_strat=copurchase&pr_rec_pid=35&pr_ref_pid=17&pr_seq=alternating"
   },
   {
     "id": 13,
     "title": "Gorgeous Wooden Computer",
     "handle": "gorgeous-wooden-computer",
     "description": null,
     "published_at": "2019-02-26T11:34:15-05:00",
     "created_at": "2019-02-26T11:34:15-05:00",
     "vendor": "Purdy Inc",
     "type": "Garden",
     "tags": [],
     "price": 930000,
     "price_min": 930000,
     "price_max": 1730000,
     "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": 25,
         "title": "Mediocre Silk Bottle",
         "option1": "Mediocre Silk Bottle",
         "option2": null,
         "option3": null,
         "sku": "",
         "requires_shipping": true,
         "taxable": true,
         "featured_image": null,
         "available": true,
         "name": "Gorgeous Wooden Computer - Mediocre Silk Bottle",
         "public_title": "Mediocre Silk Bottle",
         "options": [
           "Mediocre Silk Bottle"
         ],
         "price": 1730000,
         "weight": 5700,
         "compare_at_price": null,
         "inventory_management": "shopify",
         "barcode": null
       },
       {
         "id": 26,
         "title": "Lightweight Paper Shirt",
         "option1": "Lightweight Paper Shirt",
         "option2": null,
         "option3": null,
         "sku": "",
         "requires_shipping": true,
         "taxable": true,
         "featured_image": null,
         "available": true,
         "name": "Gorgeous Wooden Computer - Lightweight Paper Shirt",
         "public_title": "Lightweight Paper Shirt",
         "options": [
           "Lightweight Paper Shirt"
         ],
         "price": 930000,
         "weight": 6600,
         "compare_at_price": null,
         "inventory_management": "shopify",
         "barcode": null
       }
     ],
     "images": [],
     "featured_image": null,
     "options": [
       {
         "name": "Color or something",
         "position": 1,
         "values": [
           "Mediocre Silk Bottle",
           "Lightweight Paper Shirt"
         ]
       }
     ],
     "url": "/products/gorgeous-wooden-computer?pr_choice=default&pr_prod_strat=description&pr_rec_pid=13&pr_ref_pid=17&pr_seq=alternating"
   }
 ]
}
```

### 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 <product_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}&section_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&section_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? -%}
  <div id="product-recommendations">
    {%- if recommendations.products_count > 0 -%}
      {% if recommendations.intent == 'related' %}
        <h2>You may also like</h2>
      {% elsif recommendations.intent == 'complementary' %}
        <h2>Pair it with</h2>
      {% endif %}


      <ul>
        {%- for product in recommendations.products -%}
          <li className="grid__item small--one-half medium-up--one-quarter">
            <a href="{{ product.url }}">
              <span>{{ product.title }}</span>
              <span>{{ product.price | money }}</span>
            </a>
          </li>
        {%- endfor -%}
      </ul>
    {%- endif -%}
  </div>
{%- endif -%}
```

## Example section response

```html
<div id="product-recommendations">
  <h2>You may also like</h2>


  <ul>
    <li className="grid__item small--one-half medium-up--one-quarter">
      <a href="/products/gorgeous-silk-coat?pr_choice=default&pr_prod_strat=copurchase&pr_rec_pid=35&pr_ref_pid=17&pr_seq=alternating">
        <span>Gorgeous Silk Coat</span>
        <span>$380.00</span>
      </a>
    </li>
    ...
  </ul>
</div>
```

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

***