Skip to main content

For dev - Recommendation API

In this article, we want to introduce our Recommendation API and what you can do with it.

Updated this week

📖 In this article, we want to introduce our Recommendation API and what you can do with it.

Description

Recommendation API lets you query the recommendation widgets for rendering in the frontend store's theme

What can you do with Recommendation API

POST /discovery/recommend

Return recommendation products by type

Frequently bought together

FBT - AI

Params 

// Params
{
  "recommendationType": "frequently-bought-together",
  "limit": "number",
  "shop": "string",
  "wid": "string", // productpage-123456
  "event_type": "string", // default: init
  "pg": "string", // product_page, home_page, cart_page, collection_page, checkout_page
  "locale": "string", // Ex: en,....
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Body

// Body
{
  "shop": "string", // tenantId
  "recommendationType": "frequently-bought-together",
  "limit": "number",
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "modelType": "FBT",
  "secondaryAlgorithm": "string", // Ex: "bestsellers","newest-arrivals","trending-products","hand-picked-products","recently-viewed","most-viewed"
  "wid": "string", // Ex: productpage-331612,
  "productIds": "Array<number>", // Ex: [8234490986779]
  "locale": "string", // Ex: en,....
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

FBT - RuleBased

Params

// Params
{
  "recommendationType": "frequently-bought-together",
  "limit": "number",
  "shop": "string",
  "wid": "string", // productpage-123456
  "event_type": "string", // default: init
  "pg": "string", // product_page, home_page, cart_page, collection_page, checkout_page
  "locale": "string", // Ex: en,....
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Body

// Body
{
  "shop": "string", // tenantId
  "recommendationType": "frequently-bought-together",
  "limit": "number",
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "wid": "string", // Ex: productpage-331612,
  "productIds": "Array<number>", // Ex: [8234490986779]
  "locale": "string", // Ex: en,....
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
  "ruleBased": [
    {
      "type": "sameCollection",
      "status": "boolean",
      "excluded": [
        {  "type": "string" }
      ]
    },
    {
      "type": "sameProductCategory",
      "status": "boolean",
      "excluded": [
        {  "type": "string" }
      ]
    },
    {
      "type": "sameProductType",
      "status": "boolean",
      "excluded": [
        {  "type": "string" }
      ]
    },
    {
      "type": "sameVendor",
      "status": "boolean",
      "excluded": [
        {  "type": "string" }
      ]
    },
    {
      "type": "sameTags",
      "status": "boolean",
      "excluded": [
        {  "type": "string" }
      ]
    },
    {
      "type": "sameMetafield_1",
      "status": "boolean",
      "metafield": {
        "type": "string"
      }
    },
    {
      "type": "sameMetafield_2",
      "status": "boolean",
      "metafield": {
        "type": "string"
      }
    },
    {
      "type": "sameMetafield_3",
      "status": "boolean",
      "metafield": {
        "type": "string"
      }
    }
  ]
}

Related items

Related items - AI

Params

// Params
{
  "recommendationType": "related-items",
  "limit": "number",
  "shop": "string",
  "wid": "string", // productpage-123456
  "event_type": "string", // default: init
  "pg": "string", // product_page, home_page, cart_page, collection_page, checkout_page
  "locale": "string", // Ex: en,....
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Body

// Body
{
  "shop": "string", // tenantId
  "recommendationType": "related-items",
  "limit": "number",
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "modelType": "string", // Ex: Alternative, Comlementary, AIRelated
  "secondaryAlgorithm": "string", // Ex: "bestsellers","newest-arrivals","trending-products","hand-picked-products","recently-viewed","most-viewed",
  "wid": "string", // Ex: productpage-331612,
  "productIds": "Array<number>", // Ex: [8234490986779]
  "locale": "string", // Ex: en,....
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Related items - RuleBased

Params

// Params
{
  "recommendationType": "related-items",
  "limit": "number",
  "shop": "string",
  "wid": "string", // productpage-123456
  "event_type": "string", // default: init
  "pg": "string", // product_page, home_page, cart_page, collection_page, checkout_page
  "locale": "string", // Ex: en,....
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Body

// Body
{
  "shop": "string", // tenantId
  "recommendationType": "related-items",
  "limit": "number",
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "wid": "string", // Ex: productpage-331612,
  "productIds": "Array<number>", // Ex: [8234490986779]
  "locale": "string", // Ex: en,....
  "return_all_currency_fields": "boolean", // Ex: true, false. Default: false
  "ruleBased": [
    {
      "type": "sameCollection",
      "status": "boolean",
      "excluded": [
        {  "type": "string" }
      ]
    },
    {
      "type": "sameProductCategory",
      "status": "boolean",
      "excluded": [
        {  "type": "string" }
      ]
    },
    {
      "type": "sameProductType",
      "status": "boolean",
      "excluded": [
        {  "type": "string" }
      ]
    },
    {
      "type": "sameVendor",
      "status": "boolean",
      "excluded": [
        {  "type": "string" }
      ]
    },
    {
      "type": "sameTags",
      "status": "boolean",
      "excluded": [
        {  "type": "string" }
      ]
    },
    {
      "type": "sameMetafield_1",
      "status": "boolean",
      "metafield": {
        "type": "string"
      }
    },
    {
      "type": "sameMetafield_2",
      "status": "boolean",
      "metafield": {
        "type": "string"
      }
    },
    {
      "type": "sameMetafield_3",
      "status": "boolean",
      "metafield": {
        "type": "string"
      }
    }
  ]
}

Personalization recommendation

Params

// Params
{
  "recommendationType": "personalized-recommendation",
  "limit": "number",
  "shop": "string",
  "wid": "string", // productpage-123456
  "event_type": "string", // default: init
  "pg": "string", // product_page, home_page, cart_page, collection_page, checkout_page
  "locale": "string", // Ex: en,....
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Body

// Body
{
  "shop": "string", // tenantId
  "recommendationType": "personalized-recommendation",
  "limit": "number",
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "modelType": "string", // Ex: PersonalizedSearch
  "secondaryAlgorithm": "string", // Ex: "bestsellers","newest-arrivals","trending-products","hand-picked-products","recently-viewed","most-viewed","FBT","Alternative","Comlementary" 
  "wid": "string", // Ex: productpage-331612,
  "productIds": "Array<number>", // (Optional: Array can empty), Ex: [8234490986779]
  "locale": "string", // Ex: en,....
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Recently purchase

Params

// Params
{
  "recommendationType": "recently-purchased",
  "limit": "number",
  "shop": "string",
  "wid": "string", // productpage-123456
  "event_type": "string", // default: init
  "pg": "string", // product_page, home_page, cart_page, collection_page, checkout_page
  "locale": "string", // Ex: en,....
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Body

// Body
{
  "shop": "string", // tenantId
  "customerId": "string",
  "recommendationType": "recently-purchased",
  "limit": "number",
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "wid": "string", // Ex: productpage-331612,
  "productIds": "Array<number>", // (Optional: Array can empty) Ex: [8234490986779]
  "locale": "string", // Ex: en,....
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Most-viewed

Params

// Params
{
  "recommendationType": "most-viewed",
  "limit": "number",
  "shop": "string",
  "wid": "string", // productpage-123456
  "event_type": "string", // default: init
  "pg": "string", // product_page, home_page, cart_page, collection_page, checkout_page
  "locale": "string", // Ex: en,....
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Body

// Body
{
  "shop": "string", // tenantId
  "recommendationType": "most-viewed",
  "limit": "number",
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "wid": "string", // Ex: productpage-331612,
  "productIds": "Array<number>", // (Optional: Array can empty) Ex: [8234490986779]
  "locale": "string", // Ex: en,....
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Hand-picked products

Params

// Params
{
  "recommendationType": "hand-picked-products",
  "limit": "number",
  "shop": "string",
  "wid": "string", // productpage-123456
  "event_type": "string", // default: init
  "pg": "string", // product_page, home_page, cart_page, collection_page, checkout_page
  "locale": "string", // Ex: en,....
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Body

// Body
{
  "shop": "string", // tenantId
  "recommendationType": "hand-picked-products",
  "limit": "number",
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "wid": "string", // Ex: productpage-331612,
  "productIds": "Array<number>", // (Optional: Array can empty) Ex: [8234490986779]
  "locale": "string", // Ex: en,....
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Recently viewed

Params

// Params
{
  "recommendationType": "recently-viewed",
  "limit": "number",
  "shop": "string",
  "wid": "string", // productpage-123456
  "event_type": "string", // default: init
  "pg": "string", // product_page, home_page, cart_page, collection_page, checkout_page
  "locale": "string", // Ex: en,....
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Body

// Body
{
  "shop": "string", // tenantId
  "recommendationType": "recently-viewed",
  "limit": "number",
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "wid": "string", // Ex: productpage-331612,
  "productIds": "Array<number>", // Ex: [8234490986779]
  "locale": "string", // Ex: en,....
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Bestsellers

Params

// Params
{
  "recommendationType": "bestsellers",
  "limit": "number",
  "shop": "string",
  "wid": "string", // productpage-123456
  "event_type": "string", // default: init
  "pg": "string", // product_page, home_page, cart_page, collection_page, checkout_page
  "locale": "string", // Ex: en,....
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Body

// Body
{
  "shop": "string", // tenantId
  "recommendationType": "bestsellers",
  "limit": "number",
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "wid": "string", // Ex: productpage-331612,
  "productIds": "Array<number>", // (Optional: Array can empty) Ex: [8234490986779]
  "locale": "string", // Ex: en,....
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

New arrivals

Params

// Params
{
  "recommendationType": "newest-arrivals",
  "limit": "number",
  "shop": "string",
  "wid": "string", // productpage-123456
  "event_type": "string", // default: init
  "pg": "string", // product_page, home_page, cart_page, collection_page, checkout_page
  "locale": "string", // Ex: en,....
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Body

// Body
{
  "shop": "string", // tenantId
  "recommendationType": "newest-arrivals",
  "limit": "number",
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "wid": "string", // Ex: productpage-331612,
  "productIds": "Array<number>", // (Optional: Array can empty) Ex: [8234490986779]
  "locale": "string", // Ex: en,....
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Trending products

Trending products - View events

Params

// Params
{
  "recommendationType": "trending-products",
  "limit": "number",
  "shop": "string",
  "wid": "string", // productpage-123456
  "event_type": "string", // default: init
  "pg": "string", // product_page, home_page, cart_page, collection_page, checkout_page
  "locale": "string", // Ex: en,....
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Body

// Body
{
  "shop": "string", // tenantId
  "recommendationType": "trending-products",
  "calculatedBasedOn": "view-events",
  "rangeOfTime": "string", // Ex: 1-day, 2-day, 3-day,..., 7-day
  "limit": "number",
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "wid": "string", // Ex: productpage-331612,
  "productIds": "Array<number>", // (Optional: Array can empty) Ex: [8234490986779]
  "locale": "string", // Ex: en,....
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Trending products - Purchase events

Params

// Params
{
  "recommendationType": "trending-products",
  "limit": "number",
  "shop": "string",
  "wid": "string", // productpage-123456
  "event_type": "string", // default: init
  "pg": "string", // product_page, home_page, cart_page, collection_page, checkout_page
  "locale": "string", // Ex: en,....
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Body

// Body
{
  "shop": "string", // tenantId
  "recommendationType": "trending-products",
  "calculatedBasedOn": "purchase-events",
  "rangeOfTime": "string", // Ex: 1-day, 2-day, 3-day,..., 7-day
  "limit": "number",
  "layoutDisplay": "string", // Ex: carousel, bundle. Default: carousel
  "wid": "string", // Ex: productpage-331612,
  "productIds": "Array<number>", // (Optional: Array can empty) Ex: [8234490986779]
  "locale": "string", // Ex: en,....
  "return_all_currency_fields": "boolean" // Ex: true, false. Default: false
}

Response

{
  "products": {
    "type": "array",
    "item": "ProductObject"
  },
  "total": {
    "type": "number"
  },
  "debug": {
    "type": "Object"
  }
}

Example

{
  "total": 278,
  "products": [
    {
      "body_html": "Cum a rerum ut. Et dolores amet inventore corporis.",
      "skus": [],
      "available": true,
      "created_at": "2022-06-30T00:36:16-07:00",
      "review_count": 0,
      "variants": [
        {
          "merged_options": ["size:XXS", "color:Purple"],
          "inventory_quantity": 8,
          "image": null,
          "compare_at_price": null,
          "inventory_management": null,
          "fulfillment_service": "manual",
          "available": true,
          "title": "XXS / Purple",
          "inventory_policy": "deny",
          "price": "71",
          "id": 40258801401898,
          "sku": "",
          "barcode": ""
        },
        {
          "merged_options": ["size:M", "color:Purple"],
          "inventory_quantity": 2,
          "image": null,
          "compare_at_price": "71",
          "inventory_management": null,
          "fulfillment_service": "manual",
          "available": true,
          "title": "M / Purple",
          "inventory_policy": "deny",
          "price": "7",
          "id": 40258801434666,
          "sku": "",
          "barcode": ""
        },
        {
          "merged_options": ["size:L", "color:Purple"],
          "inventory_quantity": 8,
          "image": null,
          "compare_at_price": "71",
          "inventory_management": null,
          "fulfillment_service": "manual",
          "available": true,
          "title": "L / Purple",
          "inventory_policy": "deny",
          "price": "63",
          "id": 40258801467434,
          "sku": "",
          "barcode": ""
        }
      ],
      "media": [],
      "title": "Purple Mix Dress",
      "price_min": 7,
      "images_info": [
        {
          "src": "https://cdn.shopify.com/s/files/1/0567/8386/3850/products/1.jpg?v=1656574576",
          "width": 762,
          "alt": "Ipsum expedita iusto ad fugiat totam.",
          "id": 29585037852714,
          "position": 1,
          "height": 1100
        },
        {
          "src": "https://cdn.shopify.com/s/files/1/0567/8386/3850/products/4.jpg?v=1656574576",
          "width": 762,
          "alt": null,
          "id": 29585037885482,
          "position": 2,
          "height": 1100
        }
      ],
      "review_ratings": 0,
      "template_suffix": "",
      "updated_at": "2022-12-25T20:38:20-08:00",
      "collections": [
        {
          "template_suffix": "",
          "handle": "dress",
          "id": 271327232042,
          "sort_value": "09",
          "title": "Dress"
        }
      ],
      "vendor": "<a onmouseover=alert(document.cookie)>xxs link</a>",
      "percent_sale_min": 90,
      "best_selling_rank": 999999,
      "html": {
        "theme_id": 0,
        "value": ""
      },
      "id": 6840831377450,
      "published_at": "2022-06-30T00:36:14-07:00",
      "images": {
        "1": "https://cdn.shopify.com/s/files/1/0567/8386/3850/products/1.jpg?v=1656574576",
        "2": "https://cdn.shopify.com/s/files/1/0567/8386/3850/products/4.jpg?v=1656574576"
      },
      "options_with_values": [
        {
          "values": [
            {
              "image": null,
              "title": "XXS"
            },
            {
              "image": null,
              "title": "M"
            },
            {
              "image": null,
              "title": "XL"
            },
            {
              "image": null,
              "title": "XXL"
            }
          ],
          "name": "size",
          "label": "Size"
        },
        {
          "values": [
            {
              "image": null,
              "title": "Yellow"
            }
          ],
          "name": "color",
          "label": "Color"
        }
      ],
      "weight_min": 56,
      "handle": "purple-mix-dress",
      "compare_at_price_min": 71,
      "barcodes": [],
      "tags": ["collection:dresses", "style:Arty"],
      "published_scope": "webmetafields": [],
"review_ratings": 0,
"product_type": "Dresses",
"weight_max": 971,
"locations": [],
"position": null,
"compare_at_price_max": 71,
"product_category": null,
"price_max": 71,
"debugInfo": {
  "score": null,
  "sort": [
    999999,
    1656574576000
  ]
}
}
],
"debug": {
"aiResponse": []
}
}

Feel free to reach out to our dedicated support team via chat if you have any questions or require additional assistance.


​

Related Articles
Product Recommendation Best Practices Guide
Getting Recommendation Analytics
For dev - Pagination Component (App Lib V2)
For dev - Boost AI Search & Discovery API
For dev - Instant Search API
Did this answer your question?