Get Bundle Recommendations

The Bundle endpoint returns products from a Bundle Strategy saved in InOne.

• Each slot uses a pinned product, a catalog filter, or an available algorithm.

• Trigger rules choose the bundle for the current product or category. A configured fallback is used when none matches.

• Send the strategy ID and the product, category, or user context your setup needs.

For setup and details, see Create a Bundle Strategy.

Bundle Strategy availability varies by the Smart Recommender package.

Algorithm-Based or Bundle?

Two strategy types are available. See Smart Recommender Recommendation Strategies for details.

For advanced mixed-algorithm or pinned-product setups, we recommend Bundle Strategies when available in your account.

See Building Mixed Strategy or Manual Merchandising setups as a Bundle below.

Before you start

• An API token, sent in the X-Auth-Token header. Call the endpoint from your server; never put the token in a URL or in client-side code.

• A saved Bundle Strategy and its ID. To find the ID, go to Campaigns > Recommendation > Recommendation Strategies, click the info icon of your Bundle Strategy, and copy the Bundle ID. Send this value as bundleStrategyId.

• Your partner name and locale, as in Get Recommendations.

Endpoint

GET https://recommendation.api.useinsider.com/v2/bundle

Query Parameters

Required parameters are listed below. Additional context depends on your strategy; see Which Context to Send.

Which context to send

Omitting context can leave a trigger unmatched or a slot empty without failing the request. Invalid parameters and explicit exclusion parameters without userId can still return an error.

Tip: When testing, check that bundle_id is the bundle you expect and that total is not lower than planned.

How the endpoint picks the products

1. It checks each bundle's trigger against productId or categoryList, in the bundle order in InOne. A bundle without a trigger always matches.

2. It fills the first matching bundle and returns products in slot order, without duplicates. An unfilled slot adds no placeholder to data; use __context.bundle_slot_id with details=true to identify each product's slot.

3. It applies the bundle's personalization settings (see Settings saved in the strategy below).

4. If the selected bundle is below minSize or fails completely, the configured fallback is tried directly; other matching bundles are not tried. If the fallback returns no products but the first bundle had products, the first result is kept.

5. If no bundle matches, the fallback bundle is served. With no fallback, the response is successful with no products.

Settings saved in the strategy

• Saved slot filters and Advanced Personalization Criteria are applied automatically; do not repeat them in the request.

• Send userId for user-based settings and productId for settings based on the viewed product.

• Request-level viewed exclusions override saved viewed exclusions. Purchased exclusions are overridden independently.

Sample Request

Strategy 123 has two bundles:

• Complete the look (bundle ID 101):

  • triggers on selected jackets.

  • 1 pinned trouser + 3 Purchased Together products.

• Best sellers (bundle ID 102):

  • triggers on selected sneakers.

  • 4 Top Sellers products.

  • Also this bundle selected as the fallback.

A shopper views JACKET-01:

curl -X GET "https://recommendation.api.useinsider.com/v2/bundle?partnerName=mybrand&locale=en_US&currency=USD&bundleStrategyId=123&productId=JACKET-01&size=4&details=true" \
 -H "X-Auth-Token: YOUR_API_TOKEN"

const apiToken = 'YOUR_API_TOKEN';
const endpoint = 'https://recommendation.api.useinsider.com/v2/bundle';
const params = {
  partnerName: 'mybrand',
  locale: 'en_US',
  currency: 'USD',
  bundleStrategyId: '123',
  productId: 'JACKET-01',
  size: 4,
  details: true
};
const queryString = new URLSearchParams(params).toString();
fetch(`${endpoint}?${queryString}`, {
  method: 'GET',
  headers: {
    'X-Auth-Token': apiToken
  }
})
.then(response => response.json())

import requests
 
api_token = 'YOUR_API_TOKEN'
endpoint = 'https://recommendation.api.useinsider.com/v2/bundle'
 
params = {
 'partnerName': 'mybrand',
 'locale': 'en_US',
 'currency': 'USD',
 'bundleStrategyId': '123',
 'productId': 'JACKET-01',
 'size': 4,
 'details': True
}
 
headers = {
 'X-Auth-Token': api_token
}
 
response = requests.get(endpoint, params=params, headers=headers)
data = response.json()
print(data)

Sample Response

Bundle 101 matched. All IDs and products are illustrative.

{
    "success": true,
    "total": 4,
    "types": {
        "pd": 1,
        "btb": 3
    },
    "data": [
        {
            "item_id": "TROUSER-07",
            "name": "Slim Fit Trousers",
            "url": "https://www.mybrand.com/product/trouser-07",
            "image_url": "https://www.mybrand.com/images/trouser-07.jpg",
            "in_stock": 1,
            "price": { "USD": 59.0 },
            "category": ["Trousers"],
            "locale": "en_US",
            "__context": { "bundle_slot_id": 7001, "source": "static" }
        },
        {
            "item_id": "BELT-02",
            "name": "Leather Belt",
            "url": "https://www.mybrand.com/product/belt-02",
            "image_url": "https://www.mybrand.com/images/belt-02.jpg",
            "in_stock": 1,
            "price": { "USD": 25.0 },
            "category": ["Accessories"],
            "locale": "en_US",
            "__context": { "bundle_slot_id": 7002, "source": "algorithm", "type": "btb" }
        },
        {
            "item_id": "SHIRT-11",
            "name": "Oxford Shirt",
            "url": "https://www.mybrand.com/product/shirt-11",
            "image_url": "https://www.mybrand.com/images/shirt-11.jpg",
            "in_stock": 1,
            "price": { "USD": 45.0 },
            "category": ["Shirts"],
            "locale": "en_US",
            "__context": { "bundle_slot_id": 7002, "source": "algorithm", "type": "btb" }
        },
        {
            "item_id": "SCARF-04",
            "name": "Wool Scarf",
            "url": "https://www.mybrand.com/product/scarf-04",
            "image_url": "https://www.mybrand.com/images/scarf-04.jpg",
            "in_stock": 1,
            "price": { "USD": 30.0 },
            "category": ["Accessories"],
            "locale": "en_US",
            "__context": { "bundle_slot_id": 7002, "source": "algorithm", "type": "btb" }
        }
    ],
    "bundle_id": 101
}

The same request on other pages:

• A sneaker in bundle 102's trigger list: "bundle_id": 102

• A bag in neither trigger list: bundle 102 is served as the fallback, "bundle_id": 102

With no matching bundle and no fallback:

{ "success": true, "total": 0, "data": [] }

Good to know

• Pinned products are never replaced. A pinned product that is out of stock, passive, or does not match your filter leaves its slot empty.

• If an algorithm slot finds too few products, its standard fallback fills the rest; types and __context.type then show the fallback's code.

• Direct API calls are not reported in Smart Recommender analytics. To track impressions, clicks, and revenue with your own design, assign the Bundle Strategy to a JavaScript SDK-based campaign and complete the analytics-enabled integration steps in Track 2 of Integrate the JavaScript SDK-Based Smart Recommender. Assigning the strategy alone does not enable analytics tracking.

• size caps the final combined list and can remove products from later slots. minSize can trigger fallback; it does not guarantee a minimum number of returned products.

• Saved changes in InOne are not reflected immediately. Recheck the API result after an update before using it in your integration.

• Variant exclusion is set in InOne, not in the request. Go to Components > Recommendation Algorithms > Recommendation Settings and turn on Product Variant Exclusion. See Recommendation and Algorithm Settings. The excludeVariants request parameter is not supported on this endpoint. Pinned products are not affected.

Errors

The endpoint uses the standard status codes. Common cases for this endpoint:

Building Mixed Strategy or Manual Merchandising setups as a Bundle

Then call /v2/bundle?bundleStrategyId=<ID> and send the context your strategy needs.