Bundle Recommendations

Overview 📘

Bundle profiles allow for the retrieval of recommendations designed for collective purchases. Depending on the logic applied, the API may prepend a "seed" item to the response to facilitate "Shop the Look" UI components.

Base URL:https://{siteId}.a.p13n.athoscommerce.net/v1/recommend

📘

Note

{siteId} should be replaced with your site's siteId, found in your Athos management console.

⚙️ Implementation Requirements

• Configuration: Bundle profiles must be defined within the AMC.
• API Request: Use the specific profile tag in the recommendation API call.
• Seed Parameter: For seeded bundles, the products parameter must be used to pass the ID of the product used to generate the bundle.

📂 Bundle Profile Categories

🔍 Detailed Profile Specifications

1. Cross-Sell Bundle (Standard) 🔄

The primary logic used for Product Detail Pages (PDP). It identifies items that complement a specific seed product.

• Behavior: The seed item is prepended to the recommendation list.
• Metadata: The first element in the response array is marked with the bundleSeed tag.

2. Cart Cross-Sell Bundle 🛒

Optimized for Cart and Checkout pages. This profile analyzes all items currently in the user's cart to find optimal add-ons.

• Filtering: To prevent redundancy, items already present in the cart are excluded from the response.
• Metadata: As no single seed is displayed, the bundleSeed tag is omitted.

3. Trending Bundles 📈

These profiles generate "pre-packaged" bundles based on high-level site performance rather than a specific user-selected product.

• Site-wide Trending: Utilizes the site's trending bundle items to establish the seed.
• Category/Brand Trending: Identifies the top-performing bundle product within a specific category or brand and builds the bundle around that seed.
• Metadata: The lead product is returned as the first element and carries the bundleSeed tag.

4. Custom Bundle 🛠️

A fully flexible bundle configuration driven by AMC-defined ranking logic, including manual boosts and attribute filters.

• Behavior: This profile does not require a specific seed; it returns a collection of items based on the defined rule set.
• Metadata: The bundleSeed tag is not present in the response.

📝 Example Response (Seeded Bundle)

This example demonstrates a cross-sell-bundle response where the first item is the Seed.

[
  {
    "responseId": "3fe8efb5-791f-4cef-914e-90219132f9ae",
    "profile": { "tag": "cross-sell" },
    "results": [
      {
        "id": "52079546040686",
        "mappings": {
          "core": {
            "name": "Double fleece jacket",
            "price": 53,
            "sku": "PROD-12345",
            "imageUrl": "https://example.com/images/product.png",
            "available": true
          }
        },
        "variants": {
          "data": [
            {
              "mappings": { "core": { "uid": "52079546040686", "price": 103 } },
              "options": { "color": { "value": "Black" } }
            }
          ],
          "preferences": { "color": "Black" }
        },
        "bundleSeed": true 
      },
    ]
  }
]
    

Beacon Tracking

Bundle Recommendations require tracking events to capture shopper interactions with the bundle widgets. This includes tracking when bundles are rendered, which products are viewed (impressions), and when items are clicked or added to cart. These events are critical for the personalization engine to learn and improve bundle recommendations. For complete implementation details and event requirements, see the Bundle Tracking Guide.

IMPORTANT: When using the Beacon 2.0 tracking system, you must include the beacon=true parameter in your Recommendations API requests. This enables automatic tracking event generation by the API.

beacon Parameter

Set beacon=true in your Recommendations API requests to enable the new Beacon tracking system. This tells the API to generate an auto-beacon event that is sent to the tracking system automatically.

For GET requests, add beacon=true as a query parameter:

https://{siteId}.a.p13n.athoscommerce.net/v1/recommend?tags=bundle&products=123-ABC&beacon=true&...

For POST requests, include beacon: true in the request body:

{
  "products": ["123-ABC"],
  "beacon": true,
  "profiles": [...]
}

test Parameter

Set test=true to mark events as test events during development and testing. This prevents the tracking system from processing the event as a real user interaction, ensuring your test data doesn't skew analytics and reporting.

For GET requests:

https://{siteId}.a.p13n.athoscommerce.net/v1/recommend?tags=bundle&products=123-ABC&beacon=true&test=true&...

For POST requests:

{
  "products": ["123-ABC"],
  "beacon": true,
  "test": true,
  "profiles": [...]
}

Tracking Events

Bundle tracking uses dedicated /bundles/ beacon endpoints, separate from standard recommendation events:

• Bundles Render
• Bundles Impression
• Bundles Clickthrough
• Bundles Add to Cart