Recommendations Tracking Overview

This guide covers how to send tracking events for personalized recommendations using the Athos Beacon API.

Recommendations tracking events capture shopper interactions with personalized product recommendations. All events require a context object (see Context Object Guide) and event-specific data.

Base URL: https://analytics.athoscommerce.net/beacon/v2/{siteId}/recommendations/[event]

Key Difference: All recommendation events require a tag field identifying the recommendation profile.

📘
Note
{siteId} and [event] should be replaced with your site's siteId, found in your Athos management console, and the subsequent event.

Event Flow

Typical event sequence for recommendations:

Render - When recommendations requested from API and rendered on page
Impression - When recommended items enter viewport
Clickthrough OR Add to Cart - Based on shopper action

Recommendation Profile Tags

Common profile tags include:

similar - Similar products
trending - Trending products
recently-viewed - Recently viewed items
bought-together - Frequently bought together
personalized - Personalized for user

The actual tags depend on your configuration in the Athos Management Console.

Implementation Tips

Data Source: All recommendation event data comes from the Personalized Recommendations API response.

Response ID: Store the responseId from the Recommendations API response for use in all subsequent events. Batched Recommendation API responses will all contain the same responseId for each profile in the batch - use the value provided for subsequent tracking events.

Beacon 2.0 Parameter: When using Beacon 2.0 tracking, you must include beacon=true in your Recommendation API requests. This enables automatic tracking event generation by the API and ensures proper integration with the Beacon tracking system.

Test Parameter: During development and testing, include test=true in your Recommendation API requests to prevent test events from being processed as real user interactions. This keeps your analytics and reporting data clean while you validate your implementation.

Profile Tags: Store the profile tag used in the API request to include in all tracking events for those recommendations.

Multiple Profiles: If displaying multiple recommendation profiles on a single page, track each profile separately with its own events and tag value.

Viewport Visibility: For impression events, only send items currently visible. Use intersection observers to detect when items scroll into view.

Results vs. Banners: Recommendations do not currently support any merchandising banners - an empty array should be sent in the applicable banner payloads.

Mapping Product Identifiers: The Recommendations API response returns uid and sku for each product, but beacon events require parentId, uid, and sku. For products without variants (most common), set parentId equal to uid. For products with variants, parentId should be the parent product's identifier while uid is the specific variant identifier. See the Tracking Overview for detailed examples.

Quick Reference

Event	When	Required Fields
render	Recommendations rendered	`tag`, `responseId`
impression	Items visible	`tag`, `responseId`, `banners`, `results` (optional)
clickthrough	Item clicked	`tag`, `responseId`, `results` OR `banners` (1 item)
addtocart	Quick add used	`tag`, `responseId`, `results` (with qty/price)

Events

1. Render

Endpoint: POST /{siteId}/recommendations/render
When to send: Page loads and personalized recommendations are requested from API and rendered

Required data fields:

responseId - Unique ID from Recommendations API response
tag - Recommendation profile tag (e.g., "similar", "trending", "recently-viewed")

{
  "context": { /* see context guide */ },
  "data": {
    "tag": "similar",
    "responseId": "42c2dc64-d203-4d74-8122-515f26afb253"
  }
}

2. Impression

Endpoint: POST /{siteId}/recommendations/impression
When to send: Recommended products/banners scroll into view
Important: Only send items currently visible in the shopper's viewport

Required data fields:

tag - Recommendation profile tag
responseId - Unique ID from Recommendations API response
banners - Array of visible banners - NOT CURRENTLY SUPPORTED (can be empty)
results - Array of visible products (optional but recommended)

Result object:

{
  "type": "product",
  "parentId": "8128331911111",
  "uid": "8128331907370",
  "sku": "SKU-123"        // optional
}

Example:

{
  "context": { /* see context guide */ },
  "data": {
    "tag": "similar",
    "responseId": "42c2dc64-d203-4d74-8122-515f26afb253",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      },
      {
        "type": "product",
        "parentId": "8128331922222",
        "uid": "8128021070122"
      }
    ],
    "banners": []
  }
}

3. Clickthrough

Endpoint: POST /{siteId}/recommendations/clickthrough
When to send: Shopper clicks a recommended product/banner (navigates to PDP)

Required data fields:

tag - Recommendation profile tag
responseId - Unique ID from Recommendations API response
results OR banners - Single clicked item (exactly 1)

Product clickthrough:

{
  "context": { /* see context guide */ },
  "data": {
    "tag": "similar",
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      }
    ]
  }
}

4. Add to Cart

Endpoint: POST /{siteId}/recommendations/addtocart
When to send: Shopper adds recommended product via "Quick Add to Cart" button
Note: Omit if Quick Add feature not implemented

Required data fields:

tag - Recommendation profile tag
responseId - Unique ID from Recommendations API response
results - Array of products added

Product object:

{
  "parentId": "8128331911111",
  "uid": "8128331907370",
  "qty": 1,
  "price": 49.99,
  "sku": "SKU-123"        // optional
}

Example:

{
  "context": { /* see context guide */ },
  "data": {
    "tag": "similar",
    "responseId": "42c2dc64-d203-4d74-8122-515f26afb253",
    "results": [
      {
        "parentId": "8128331911111",
        "uid": "8128331907370",
        "qty": 1,
        "price": 49.99
      }
    ]
  }
}

Bundle Tracking

This section covers how to send tracking events for personalized bundle recommendations using the Athos Beacon API.

Bundle tracking events capture shopper interactions with bundle recommendation sets rendered on a page. Like standard recommendation events, all bundle events require a context object (see Context Object Guide) and event-specific data.

Base URL: https://analytics.athoscommerce.net/beacon/v2/{siteId}/bundles/[event]

Key Difference: Bundle events use the /bundles/ path instead of /recommendations/, and the tag field identifies the bundle profile (e.g., "bundle").

📘
Note
{siteId} and [event] should be replaced with your site's siteId, found in your Athos management console, and the subsequent event.

Bundle Event Flow

Typical event sequence for bundle recommendations:

Render - When bundle recommendations are requested from the API and rendered on the page
Impression - When bundle items enter the viewport
Clickthrough OR Add to Cart - Based on shopper action

Bundle Quick Reference

Event	When	Required Fields
render	Bundles rendered	`tag`, `responseId`
impression	Items visible	`tag`, `responseId`, `banners`, `results`
clickthrough	Item clicked	`tag`, `responseId`, `results` OR `banners` (1 item)
addtocart	Quick add used	`tag`, `responseId`, `results` (with qty/price)

Bundle Events

1. Render

Endpoint: POST /{siteId}/bundles/render
When to send: Page loads and personalized bundle recommendations are requested from the API and rendered

Required data fields:

responseId - Unique ID from the Recommendations API response
tag - Bundle profile tag (e.g., "bundle")

{
  "context": { /* see context guide */ },
  "data": {
    "tag": "bundle",
    "responseId": "42c2dc64-d203-4d74-8122-515f26afb253"
  }
}

2. Impression

Endpoint: POST /{siteId}/bundles/impression
When to send: Bundle products/banners scroll into view
Important: Only send items currently visible in the shopper's viewport

Required data fields:

tag - Bundle profile tag
responseId - Unique ID from the Recommendations API response
results - Array of visible bundle products
banners - Array of visible banners (send as empty array if none)

Result object:

{
  "type": "product",
  "parentId": "8128331911111",
  "uid": "8128331907370"
}

Example:

{
  "context": { /* see context guide */ },
  "data": {
    "tag": "bundle",
    "responseId": "42c2dc64-d203-4d74-8122-515f26afb253",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      },
      {
        "type": "product",
        "parentId": "8128331922222",
        "uid": "8128021070122"
      }
    ],
    "banners": []
  }
}

3. Clickthrough

Endpoint: POST /{siteId}/bundles/clickthrough
When to send: Shopper clicks a bundle product/banner and is taken to the product detail page (PDP)

Required data fields:

tag - Bundle profile tag
responseId - Unique ID from the Recommendations API response
results OR banners - Single clicked item (exactly 1)

Product clickthrough:

{
  "context": { /* see context guide */ },
  "data": {
    "tag": "bundle",
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      }
    ]
  }
}

4. Add to Cart

Endpoint: POST /{siteId}/bundles/addtocart
When to send: Shopper adds a bundle product via "Quick Add to Cart" button
Note: Omit if Quick Add feature not implemented

Required data fields:

tag - Bundle profile tag
responseId - Unique ID from the Recommendations API response
results - Array of products added

Product object:

{
  "parentId": "8128331911111",
  "uid": "8128331907370",
  "qty": 1,
  "price": 49.99
}

Example:

{
  "context": { /* see context guide */ },
  "data": {
    "tag": "bundle",
    "responseId": "42c2dc64-d203-4d74-8122-515f26afb253",
    "results": [
      {
        "parentId": "8128331911111",
        "uid": "8128331907370",
        "qty": 1,
        "price": 49.99
      }
    ]
  }
}