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 Show product recommendations.

GET /recommendations/products.json

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

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

Products response

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

Error responses

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

Invalid parameter

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

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:

GET /recommendations/products

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

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

Section response

The response to a successful request to the /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:

Error responses

When a request to the /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.

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

To learn more about product recommendation reports, see Product recommendation conversion over time.