Product Recommendations API reference

The following calls can be submitted via the Product Recommendations API to your Shopify shop.

For more information on how to use product recommendations on your Shopify shop, see the following tutorials:

GET /recommendations/products.json

For a given product, display recommended products on the product page.

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

Query parameters

product_id (required): The unique product ID of the product that you want to show recommended products for.

limit (optional): Limits number of results, up to a maximum of ten. Using the limit parameter cannot increase the number of results over ten. A maximum of ten results are given when this is not used.

section_id (optional): The unique section ID of the section file that you want render with product recommendations. When this parameter is used, the JSON response is a string of HTML of the rendered section.

Example call using jQuery:

jQuery.getJSON("/recommendations/products.json?product_id=17&limit=4", function(
 response
) {
 var recommendedProducts = response.products;
 if (recommendedProducts.length > 0) {
   var firstRecommendedProduct = recommendedProducts[0];
   alert(
     "The title of the first recommended product is: " +
       firstRecommendedProduct.title
   );
 }
});

Example call using Fetch:

fetch("/recommendations/products.json?product_id=17&limit=4")
 .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
       }`
     );
   }
 });

Responses

The response of the Product Recommendations API is a JSON object when a product_id is provided with no accompanying section_id. When a section_id is provided, the response will be a string of HTML.

Products response

When a valid product_id parameter is provided with no optional section_id, the endpoint returns a JSON object. Example JSON object:

{
 "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"
   }
 ]
}

Section response

When a valid product_id and section_id parameter are provided, the endpoint returns a string of HTML of the rendered section file associated to the section_id. For example:

<div id="shopify-section-product-recommendations">
  <h2>You may also like</h2>
  <ul>
    <li class="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

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

{
  "status": 422,
  "message": "Invalid parameter error",
  "description": "A product_id value is missing"
}

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

If the section_id is for a section file that doesn't exist, then the endpoint returns the following error:

{
  "status": 404,
  "message": "Section not found",
  "description": "No section with id <section_id> was found in the theme"
}

Tracking conversions for product recommendations

The url property for each product in the JSON 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.