Public recommendations API

Don't need the widget, but still want our recommendation engine? The Frequently Bought Together public API lets you pull the exact same product recommendations we calculate for your store — with all your configured settings applied — and use them anywhere you like: a custom-built widget, a mobile app, an email campaign, or any other integration.

Endpoint

GET https://cdn.codeblackbelt.com/public/api/v1/frequently-bought-together

Example request:

https://cdn.codeblackbelt.com/public/api/v1/frequently-bought-together?productId=2288305471584&shop=my-store.myshopify.com&includeMainProduct=true

Query parameters

Parameter	Type	Required	Description
`productId`	number	Yes	The numeric Shopify ID of the product you need recommendations for.
`shop`	string	Yes	Your store's `.myshopify.com` domain.
`includeMainProduct`	boolean	No — defaults to `false`	When `true`, the first item in `recommendations` is the requested product itself, not a recommendation. Useful if you want to render the main product alongside its recommendations from a single response.

Example response

{
  "recommendations": [
    {
      "id": 7431267254369,
      "handle": "palladium-pallatech-hi-tx-chevron",
      "title": "PALLADIUM | PALLATECH HI TX | CHEVRON",
      "description": "The Palladium iconic classic receives a subtle, yet stylish update...",
      "type": "SHOES",
      "vendor": "PALLADIUM",
      "tags": ["men", "winter"],
      "featured_image": "https://cdn.shopify.com/s/files/.../product.jpg",
      "featured_image_alt_text": "PALLADIUM | PALLATECH HI TX | CHEVRON",
      "published_at": 1764958264,
      "updated_at": 1784513278,
      "variants": [
        {
          "id": 42668247285857,
          "title": "9 / red",
          "price": 159.95,
          "compare_at_price": null,
          "available_for_sale": true,
          "image": "https://cdn.shopify.com/s/files/.../product.jpg",
          "image_alt_text": "PALLADIUM | PALLATECH HI TX | CHEVRON",
          "barcode": null,
          "sku": "PAL-01-9-red"
        }
      ],
      "collections": []
    }
  ]
}

Each recommendation includes full product information — title, description, type, vendor, tags, featured image, publish/update dates — along with its variants (price, compare-at price, availability, image, barcode, SKU) and collections, so you have everything you need to render a rich product card without extra Shopify API calls.

Error responses

Status	Meaning
`400 Bad Request`	The `productId` parameter is missing or isn't a valid number.
`403 Forbidden`	The store is unknown to us, or doesn't have an active subscription.
`429 Too Many Requests`	The per-minute request quota for your store has been exceeded.

{
  "error": {
    "code": 400,
    "message": "Bad Request"
  }
}

Good to know

An active subscription is required. The API won't return data for stores without one.
Your settings are respected. Recommendations are calculated using your configured preferences — global recommendations, manual recommendations, bundle tuning, discount rules, and so on — exactly like the widget.
Generous rate limits. We allow a considerable number of requests per minute per store. If you exceed it, you'll get a 429 response — simply wait a moment and retry.
Primary market only. Product information is returned for your store's primary market. If you need pricing/availability for other markets, query the Shopify Storefront/Admin API directly using the returned product/variant IDs.
Read-only. This API only returns recommendation data — it doesn't perform widget-specific actions such as creating discounts or registering analytics events. Those only happen through the widget itself.