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

Profile Type	Logic Description	Seed Source	`bundleSeed` Tag
Cross-Sell (PDP)	Standard cross-sell logic based on a specific product.	Current PDP page Product	Included
Cart Cross-Sell	Recommendations based on current cart contents.	Active Cart	Excluded
Trending (Site)	First non-excluded trending bundle product sitewide	Bundle Trending	Included
Category/Brand	Top product in Category/Brand + cross-sells.	Category/Brand Lead	Included
Custom Bundle	Determined by AMC boost rules, sorts, and filters.	Rule-based	Excluded

🔍 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:

Event	Endpoint	When to Send
render	`/{siteId}/bundles/render`	Bundle results are requested and rendered
impression	`/{siteId}/bundles/impression`	Bundle items scroll into the shopper's viewport
clickthrough	`/{siteId}/bundles/clickthrough`	Shopper clicks a bundle item to view its PDP
addtocart	`/{siteId}/bundles/addtocart`	Shopper adds a bundle item via Quick Add