Implementation Order

🏗️ Build in the Right Order

Getting the sequence right saves debugging time. Several things in Athos have hard dependencies: cookies must exist before API calls fire, responseId must be captured before tracking events can attach to it, and Shopping Platform events must be flowing before Recommendations or Personalization are meaningful. This guide walks the full build sequence from setup to production-ready.

✅ Step 1 — Cookies

Set these cookies on every page load, before any API calls are made.

User Tracking Cookies (Required for all integrations)

Both values must be UUID v4 format. See UUID v4 Generation →

Personalization Tracking Cookies (Required if using Personalized Search & Merchandising or Recommendations)

Set the cookie first. The API query string parameters source their values from these cookies.

See Athos Cookies →

✅ Step 2 — Beacon Tracking

Initialize your tracker before any user interaction can happen. Tracking is the backbone of analytics, personalization, and recommendations. The earlier it's live, the more data you accumulate.

Beacon 2.0 is the Athos tracking event system — the standard for what events to send and how. It covers all core event types: autocomplete, search, category, recommendations, and shopping platform events (product views, cart, orders).

There are two ways to implement it:

If using Beacon 2.0 API

• Build a shared context object utility (every beacon event requires it):

{
  "context": {
    "timestamp": "2024-06-11T17:47:04.075876Z",
    "pageUrl": "https://yourstore.com/search?q=jacket",
    "userId": "<athosUserId cookie value>",
    "sessionId": "<athosSessionId cookie value>",
    "pageLoadId": "<UUID v4 — generate once per page load, reuse across events>",
    "initiator": "yourcompany/custom/1.0"
  }
}

See Beacon Tracking → · Beacon.js →

✅ Step 3 — Autocomplete

Autocomplete is the entry point to search. Users type, suggestions fire, queries form. Wire this up before Search so the full query flow is tracked from the start.

API setup — three endpoints work together:

• Trending API (optional): call on search bar focus, before the shopper types, to show popular searches
• Suggest API: call as the shopper types (recommended: after 2+ characters with a 50ms debounce) to fetch query suggestions
• Autocomplete API: call with the current query (or hovered suggestion) to fetch product previews; use this endpoint, not the Search API, for autocomplete product results

Required query string params on every Autocomplete API request: userId, sessionId, pageLoadId, domain (from window.location.href), and beacon=true

For accurate reporting, also pass:

• source — where the query came from: suggested, historical, trending, or input (default when user types freely)
• input — what the user actually typed, which may differ from q when the user hovers or selects a suggestion

Store the responseId from each response.

Tracking events to wire up alongside the API:

All events sent to: https://analytics.athoscommerce.net/beacon/v2/{siteId}/autocomplete/[event]

Merchandising Features

Merchandising data comes back inside the Autocomplete API response. No separate API call is needed. This step is purely about rendering and tracking what the API already returns.

Banners (inline + hero):

• Check the response for merchandising.content (inline banners within results)
• Check for merchandising.banner (banners located outside of results grid i.e header/footer etc.)
• Track banner impressions and clicks

Did You Mean:

• Check didYouMean. If present and results are sparse, surface the corrected query suggestion

See Autocomplete → · Beacon Tracking → · Integrating Banners →

✅ Step 4 — Search + Category

Search and Category use nearly identical API patterns: same required params, same response shape, same beacon=true requirement. Implement and track them together.

API setup:

• Required query string params on every request: userId, sessionId, pageLoadId, domain (from window.location.href)
• For Search: pass q with the submitted search query
• For Category: pass bgfilter with the category identifier — this is required to define the category scope and differentiate it from customer-applied filters
• Store the responseId from each response

Required for correct reporting and merchandising:

• Do not apply a default sort on initial page load. Let Athos return results in their natural order so merchandising rules and relevancy work as configured.
• Do not filter, sort, or paginate client-side. All of these must go through the API — client-side manipulation breaks reporting and bypasses merchandising rules.

Search tracking events:

All search events sent to: https://analytics.athoscommerce.net/beacon/v2/{siteId}/search/[event]

Category tracking events:

All category events sent to: https://analytics.athoscommerce.net/beacon/v2/{siteId}/category/[event]

Merchandising Features

Merchandising data comes back inside the Search, and Category API responses. No separate API call is needed. This step is purely about rendering and tracking what the API already returns.

Banners (inline + hero):

• Check the response for merchandising.content (inline banners within results)
• Check for merchandising.banner (banners located outside of results grid i.e header/footer etc.)
• Track banner impressions and clicks

Redirect:

• Check merchandising.redirect. If present, navigate the user to that URL instead of rendering results

Did You Mean:

• Check didYouMean. If present and results are sparse, surface the corrected query suggestion

See Search → · Category → · Search Tracking → · Category Tracking → · Integrating Banners →

✅ Step 5 — Products API

The Products API returns full variant-level data for a given parent product — images, prices, SKUs, availability, options (color, size), badges, and display attributes. Call it when a shopper navigates to a PDP or triggers a quick view overlay.

Endpoint: GET /v1/products/{parentId}

When to call it:

• On every PDP load, using the parentId from the search or category result the shopper clicked
• On quick view overlays in search or category grids (if implemented)

What it returns:

• variants.data — the full list of variants with their options, pricing, images, and availability
• variants.optionConfig — the option structure (e.g., color as swatch, size as dropdown) to drive your variant selector UI
• mappings.core.description — the product description

See Products API →

✅ Step 6 — Shopping Platform Events

These events capture core commerce behavior and are required for Personalization and Reporting. The Recommendations engine needs product/pageview and order/transaction data flowing before it can generate meaningful results.

Optionally implement these using Beacon.js directly, or — if you're on Shopify — the Shopify Web Pixel can handle them automatically in place of manual implementation.

These events also trigger Preflight calls in Step 8.

See Beacon Tracking →

✅ Step 7 — Personalization / Preflight (Optional — account feature)

The Preflight API primes Athos's personalization cache ahead of Search, Autocomplete, and Recommendations requests, improving response times and result relevance.

When to call Preflight:

Required params: siteId, userId Optional params: shopper, cart, lastViewed

The response can be ignored. Its only purpose is to notify Athos so personalization data is cached before the next API call.

See Personalization →

✅ Step 8 — Recommendations (Optional — account feature)

API setup:

• Use POST /recommend (preferred) or GET /recommend
• Pass profile tags, products (for cross-sell on PDPs), and beacon=true
• Pass shopper, cart, and lastViewed for personalized results
• Store the responseId from each response

Tracking events to wire up alongside the API:

All recommendations events sent to: https://analytics.athoscommerce.net/beacon/v2/{siteId}/recommendations/[event]

See Recommendations → · Recommendations Tracking →

✅ Step 9 — Segmented Merchandising (Optional — account feature)

Segmented Merchandising allows you to pass customer segment data with Search and Category requests to receive segment-specific merchandising rules. Implement this after core search and merchandising are stable.

See Segmented Merchandising →

📋 Summary

For a detailed checklist with checkboxes, see the API Integration Checklist →