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.

To learn how to show product recommendations in your theme, refer to Product recommendations.

All Ajax API requests should use locale-aware URLs to give visitors a consistent experience.

Note

The Shopify Search & Discovery app enables users to customize product recommendation and search results, which can impact results from storefront search and the Ajax Product Recommendations API. To learn about how these results can be impacted, visit the Shopify Help Center.

Anchor to GET /{locale}/recommendations/products.jsonGET /{locale}/recommendations/products.json

The following example request retrieves the recommended products for a specific product:

GET /{locale}/recommendations/products.json?product_id={product-id}&intent={intent}

Anchor to Query parametersQuery parameters

Query parameter Required Description

product_id Yes The unique product ID of the product that you want to show recommended products for.

limit

Limits the number of results.

The value can range from 1 to 10, and the default is 10.

intent

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.

The accepted values are related and complementary. The default value is related.

Example request object

{

"product_id": "1234567890123",

"limit": 4,

"intent": "related"

}

Example request using Fetch

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}`

);

}

);

Anchor to Products responseProducts response

The following example is a response to a successful request to the /{locale}/recommendations/products.json endpoint:

Example product response

{

"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",

Anchor to Error responsesError responses

When a request to the /{locale}/recommendations/products.json endpoint is unsuccessful, one of the following error responses is returned:

Invalid parameter
Product not found

Anchor to Invalid parameterInvalid parameter

In the absence of a product_id parameter, the endpoint returns the following error:

{

"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:

{

"status": 422,

"message": "Invalid parameter error",

"description": "The intent parameter must be one of related, complementary"

}

Anchor to Product not foundProduct 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:

{

"status": 404,

"message": "Product not found",

"description": "No product with id <product_id> is published in the online store"

}

Anchor to GET /{locale}/recommendations/productsGET /{locale}/recommendations/products

The following example request retrieves the HTML from a section rendered with product recommendations for a specific product.

GET /{locale}/recommendations/products?product_id={product-id}&section_id=product-recommendations

Anchor to Query parametersQuery parameters

Query parameter	Required	Description
`product_id`	Yes	The unique 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 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. The following values are accepted: `related`, `complementary`. The default value is `related`.

Example request object

{

"product_id": "1234567890123",

"limit": 4,

"section_id": "product-recommendations",

"intent": "related"

}

Example request using Fetch

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;

}

});

Anchor to Section responseSection 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 containing the recommended products for the specified product.

For example, the following section would generate the following section response:

Example section

{%- if recommendations.performed? -%}

{%- if recommendations.products_count > 0 -%}

{% if recommendations.intent == 'related' %}

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

{% endif %}

<ul>

{%- for product in recommendations.products -%}

<span>{{ product.title }}</span>

<span>{{ product.price | money }}</span>

</a>

</li>

{%- endfor -%}

</ul>

{%- endif -%}

</div>

{%- endif -%}

Example section response

<ul>

<span>Gorgeous Silk Coat</span>

</a>

</li>

...

</ul>

</div>

Anchor to Error responsesError 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`.

Anchor to Tracking conversions for product recommendationsTracking conversions for product recommendations

The url property for each product in the 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 contains this tracking information as well. The URL uses the following format:

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

Was this page helpful?