Glossary

Definitions for terms used throughout the Athos Commerce documentation.

A reference for terms you'll encounter across the Athos Commerce docs. Entries are alphabetical.


A/B Testing

A merchandising feature that lets you test variations of a campaign against each other. Experiment data is returned in merchandising.experiments in the API response. Also referred to as Experiments.

See: Athos Management Console


addToCart event

A beacon event fired when a shopper adds a product to their cart via a Quick Add to Cart button on a results page (search, autocomplete, category, recommendations, bundles, or chat). Requires responseId from the originating API response and the product's uid, parentId, qty, and price, plus tag for recommendations and bundles and chatSessionId for chat. For cart changes originating outside of a results module, use cart events instead.

See: Beacon Tracking Overview


AMC

See Athos Management Console.


Athos Management Console

The web dashboard at console.athoscommerce.net where teams configure merchandising campaigns, field settings, filters, sorting options, landing pages, and account details. Your siteId is found here under My Account. Also referred to as the AMC.


athos_attribution

A URL query parameter used to pass campaign attribution data into beacon tracking. Beacon.js reads it from the page URL automatically and includes it in the context of later events in the same session — no manual configuration required.

Format: ?athos_attribution=channel:campaign-id
Example: ?athos_attribution=email:summer-sale-2025

See: Beacon.js Guide


athosCartProducts

A session cookie that stores a comma-separated list of the SKUs or UIDs of products currently in the shopper's cart. Sent as the cart query parameter in Search, Autocomplete, Category, and Recommendations API requests, where it powers cart-aware personalization. Managed automatically by Beacon.js.

See: Athos Cookies Guide


athosSearchedQueries

The local storage key where Beacon.js keeps the shopper's recent search queries, one list per siteId (athosSearchedQueries-<siteId>). Holds up to 10 queries, most recent first. Beacon.js doesn't record queries itself - the integration adds each one with beacon.storage.searched.add([query]). Queries from the past 2 weeks are sent as the lastSearches parameter in preflight and in Autocomplete, Search, and Recommendations API requests.

See: Beacon.js Guide — Searched Queries


athosSessionId

A cookie that identifies the shopper's current visit. Must be a UUID v4. Maps to sessionId in the beacon context object. Managed automatically by Beacon.js.

See: Athos Cookies Guide


athosShopperId

A cookie that stores the authenticated shopper's ID. Sent as the shopper query parameter in API requests, where it enables personalized search results and recommendations for logged-in shoppers. Beacon.js sets it when the integration reports a login with shopper.login or setShopperId.

See: Athos Cookies Guide


athosUserId

A persistent cookie that uniquely identifies a shopper across visits. Must be a UUID v4. Maps to userId in the beacon context object. Managed automatically by Beacon.js. Do not regenerate this value on each visit — stability is required for accurate analytics.

See: Athos Cookies Guide


athosViewedProducts

A persistent cookie that stores a list of recently viewed product SKUs or UIDs, most recent first. Sent as the lastViewed query parameter in API requests, where it powers "recently viewed" and affinity-based recommendation profiles. Managed automatically by Beacon.js.

See: Athos Cookies Guide


Autocomplete

The search suggestion module that provides type-ahead results — suggested queries and matching products — as a shopper types into a search input. Uses the Suggest API for query suggestions and the Autocomplete API for product results. Suggest API requests are typically sent after 2+ characters with a 50ms debounce.

Beacon events: render, impression, clickThrough, addToCart, redirect

See: Autocomplete Tracking Guide


Background Filter (bgfilter)

A pre-filter applied to API results before they are returned to the shopper. Used to scope results to a specific context — for example, restricting a category page to only show products in that category. The shopper can't change it, and reporting keeps it separate from shopper-applied filters. Distinct from customer-applied filters.


Banner

HTML content configured by a merchant in the Athos Management Console and returned in Search, Autocomplete, and Category API responses under merchandising.content. Banners appear in positions defined by the API: header, banner (secondary), footer, left, or inline. Your integration is responsible for rendering the HTML in the correct position and tracking impressions and clickThroughs.

See: Banner ID Extraction Guide


banner uid

The identifier for a specific merchandising banner, extracted from the data-banner-id attribute in the banner's HTML string. Used in the uid field of the banners array in beacon event payloads. Not the same as a product uid.

htmlString.match(/data-banner-id="(\d+)"/)

See: Banner ID Extraction Guide


Beacon 2.0

See Beacon API v2.


Beacon API v2

The backend analytics REST API that receives all tracking events. Also referred to as Beacon 2.0. Replaces the legacy Beacon and IntelliSuggest tracking. Most integrations send events through Beacon.js rather than calling this API directly.

Base URLs:

  • Athos: https://analytics.athoscommerce.net/beacon/v2/{siteId}/[module]/[event]
  • Searchspring: https://analytics.searchspring.net/beacon/v2/{siteId}/[module]/[event]

See: Beacon Tracking Overview, Beacon Migration Guide


Beacon.js

The official Athos Commerce TypeScript library for sending Beacon API v2 tracking events. Handles event batching, session and user ID persistence, cart state, viewed products history, and attribution tracking automatically. Available via CDN or NPM.

See: Beacon.js Guide


Beacon.js CDN

One of two installation paths for Beacon.js. The CDN script initializes automatically on load and exposes window.athos.tracker as the global entrypoint. Designed for platform template integrations (BigCommerce, Magento, Shopify) where you add the script directly in storefront theme files. Place before the closing </head> tag.

<script siteId="YOUR_SITE_ID" src="https://cdn.athoscommerce.net/analytics/beacon.js"></script>

See: Beacon.js Guide


Beacon.js NPM

One of two installation paths for Beacon.js. Use the NPM package when your integration runs in a JavaScript/TypeScript application and you want typed imports, versioned dependency management, and build-time tooling integration.

npm install --save @athoscommerce/beacon

See: Beacon.js Guide


Boost Rules

A merchandising feature that controls product visibility and ranking in results — elevating specific products, demoting others, or removing them from results entirely. Configured in the Athos Management Console. Elevated products are listed by ID in merchandising.is_elevated, pinned products in merchandising.elevated, and removed products in merchandising.removed.


Breadcrumbs

An array returned in Search and Category API responses describing the current navigation state — the search query and the filters applied. Each item includes removeFilters and removeRefineQuery for building breadcrumb navigation. For a removable list of applied filters, use filterSummary.


Bulk Indexing API

See Indexing API.


Bundles

A module that surfaces personalized product bundle sets on a page (typically a PDP). Uses the same event shape as Recommendations but targets the /bundles/ Beacon API path. Requires a tag matching the bundle profile configured in the Athos Management Console.

Beacon events: render, impression, clickThrough, addToCart

See: Recommendations Tracking Guide


Cart events

Beacon events that track cart changes outside of a Quick Add to Cart action on a results page. cart.add fires when a product is added or its quantity increases; cart.remove fires when a product is removed or its quantity decreases. Both require a results array (what changed) and a cart array (the full cart state after the action).

See: Shopping Platform Tracking Guide


cart parameter

See athosCartProducts.


Category

The module for product listing pages (PLPs). Uses the same response format as the Search API but scoped to a specific category via bgfilter.

Beacon events: render, impression, clickThrough, addToCart

See: Category Tracking Guide


Chat events

Beacon events for tracking products surfaced to a shopper through a Conversational Assistant chat session. Every chat event requires a chatSessionId to associate it with the specific conversation.

Events: impression, clickThrough, addToCart, feedback

See: Chat Tracking Guide


chatSessionId

A string identifier that ties chat beacon events to a specific shopper conversation. Returned by the Init API and required on all chat events.


clickThrough event

A beacon event fired when a shopper clicks a product (to view its detail page) or a banner (to follow its link). For module events (search, autocomplete, recommendations, etc.), the results or banners array must contain exactly one item — the specific item clicked.


context object

A required component of every Beacon API v2 event payload. Contains session and environment metadata used for attribution, reporting, and personalization. Six fields are required: timestamp, pageUrl, userId, sessionId, pageLoadId, and initiator.

{
  "context": {
    "timestamp": "2024-06-11T17:47:04.075876Z",
    "pageUrl": "https://example.com/search?q=shirts",
    "userId": "41f87850-...",
    "sessionId": "1c311c14-...",
    "pageLoadId": "080d179f-...",
    "initiator": "athos/custom/1.0"
  },
  "data": { ... }
}

See: Context Object Guide


Conversational Assistant

A chat experience on your storefront where shoppers ask questions in natural language, search for and compare products, find similar items, get inspiration, and search by image. Integrations check availability with the Status API, start a session with the Init API to get a chatSessionId, and send messages with the Send API. Tracked with chat events. Currently in beta - contact your Customer Success Manager to join.

See: Conversational Assistant API Reference


dev flag

A boolean field (dev: true) in the beacon context object that excludes an event from production reporting. Use during development and testing. Beacon.js's mode: 'development' sets this automatically.


Did You Mean

A zero-results feature that returns a spelling suggestion in the didYouMean object when a search returns no results. When it's present, your implementation should render a link to the suggested query (e.g., "Did you mean blue shirts?").


Experiments

See A/B Testing.


Express Sync

See Indexing API.


Facets

Filterable attributes returned in API responses representing the available filter options (colors, sizes, brands, price ranges, etc.) for the current result set. Displayed in the order returned. Which fields become facets is set in Field Settings, and how they display is set in Filter Configuration. Merchandising campaigns can also reorder or hide facets.


Feed

See Product Feed.


feedback event

A chat beacon event fired when a shopper rates the chat session as a whole with a thumbs up or down. Requires chatSessionId and feedback (positive or negative).

See: Chat Tracking Guide


Field Settings

Admin configuration in the Athos Management Console that controls which product data fields are indexed, searchable, filterable, and displayed in API responses. Determines which attributes appear as facets and which fields the search engine matches against.


Filter

A query parameter applied by the shopper to narrow results to specific attribute values (e.g., color = blue, size = medium). Filters must be applied via the API — never client-side — so that result counts, facet values, and analytics remain accurate. Displayed in the results page facet panel.

Distinct from Background Filter, which is applied by your integration rather than the shopper.


Filter Configuration

An admin tool in the Athos Management Console for configuring how facets display in results, such as whether each is expanded or collapsed by default.


Geographic Merchandising

A merchandising feature that applies location-based campaign rules based on the shopper's IP address.


impression event

A beacon event fired when products or banners enter the shopper's viewport. Only include items that are actually visible — do not send off-screen items. Typically implemented with the IntersectionObserver API. Standard threshold: 70% of the element visible for at least 1000ms.

See: Impression Tracking Guide


Indexing API

A set of endpoints for keeping your product data in sync with Athos. Two modes:

  • Bulk Indexing — triggers a full reindex of your product feed. The PUT version has Athos download your configured feed, and the POST version uploads a feed file. Limited to one reindex request per hour.
  • Live Indexing (Express Sync) — queued upsert, update, and delete operations for individual products between bulk runs (3MB request body, up to 500 products per request; must be enabled by Athos)

Both authenticate with your siteId and Secret Key.

See: Bulk Indexing API Reference, Express Sync Indexing API Reference


initiator

A string field in the beacon context object that identifies the source of the tracking event — your application, framework, and version (e.g., athos/custom/1.0). Beacon.js sets this automatically. For direct API integrations, set it to something descriptive so events are identifiable in reports.


Inline Banner

A banner positioned within the product results grid at a specified index. Unlike header/footer/left banners, inline banners occupy a grid slot, which reduces the number of product results returned in that response to accommodate the banner's position.


IntelliSuggest

The legacy Searchspring tracking system, retired in favor of Beacon API v2 and Beacon.js. Its _isuid cookie is deprecated. If your site still sets _isuid, it must share the same value as athosUserId.

See: Athos Cookies Guide


_isuid

See IntelliSuggest.


Landing Page

A search results page driven by a tag URL parameter on your site instead of a search query. Merchants configure landing pages in the Athos Management Console and assign products to them. Your integration reads the tag and passes it to the Search API as the landing-page parameter to retrieve those products. Tags must be lowercase and contain only letters, numbers, and hyphens.


lastSearches parameter

See athosSearchedQueries.


lastViewed parameter

See athosViewedProducts.


Live Indexing API

See Indexing API.


login event

A beacon event fired when a shopper logs into their account. Links the session to the shopper's shopperId, which goes in the context object. With Beacon.js, shopper.login or setShopperId sends it, stores the ID in the athosShopperId cookie, and sends a preflight request.

See: Beacon.js Guide


Merchandising

The set of features that let merchants control how results are presented — banners, redirects, product boosting/pinning, landing pages, A/B tests, and segmentation. Configured in the Athos Management Console. Merchandising data is returned in the merchandising object of Search, Autocomplete, and Category API responses.


Merchandising Campaign

A set of rules configured in the Visual Merchandiser that applies to specific pages or queries. A campaign can include banners, redirects, boosted/removed products, and other overrides. Campaigns are triggered when their configured context (query, category, filters, landing page, segment tag, or location) matches the current request. Active campaigns are returned in merchandising.triggeredCampaigns.

Campaign types: Search (specific query), Search Contains (query contains keyword), Category (category page), Mixed (multiple contexts)


Meta API

An endpoint that returns static search configuration data, most notably badge configurations, rather than results.

See: Meta API Reference


pageLoadId

A UUID that scopes beacon events to a single page load. All events fired on the same page share the same pageLoadId. Generate a new one on every page load, and in SPAs, on every route change. Never reuse it across navigations. Beacon.js keeps it briefly in local storage and reuses it only when the same URL reloads within 10 seconds.

See: Context Object Guide


pageView event

A beacon event fired on every Product Detail Page (PDP) load. Records the viewed product and automatically updates the shopper's viewed products history for personalization. Beacon.js sends it once per unique variant per page load and URL path, so repeat calls for the same variant are ignored until the path changes or pageLoad() is called.

beacon.events.product.pageView({ data: { result: { uid, parentId, sku } } });

See: Shopping Platform Tracking Guide


parentId

The identifier of the parent product. For products with variants (e.g., a shirt in multiple sizes/colors), parentId is the parent's ID and uid is the specific variant's ID. For simple products with no variants, set parentId and uid to the same value. Required in all product result objects in beacon event payloads.

See: Beacon Tracking Overview — Mapping Product Data


PDP

Product Detail Page. The individual product page a shopper lands on after clicking a result. Fire a pageView event on every PDP load.


Personalization

A platform feature that delivers shopper-specific results and recommendations based on behavior, cart contents, viewed products, and authenticated identity. Powered by the shopper, cart, lastViewed, and lastSearches parameters on API requests. Primed via the Preflight API.


Preflight

A request to the Athos personalization API (/v1/preflight) that primes the personalization cache with the current shopper's cart, viewed products, recent searches, and shopper ID before Autocomplete or Search API calls are made. Improves personalization response times. Beacon.js sends preflight automatically when shopper, cart, viewed products, or recent searches change; it can also be triggered manually via beacon.sendPreflight().

See: Personalization Overview, Beacon.js Guide


Product Feed

A data file (CSV, XML, or custom format) containing all product information to be indexed by Athos. The feed is the source of truth for product data in search results. Triggered for reindexing via the Bulk Indexing API.


Product Finder

A guided selling tool with dropdown selectors that helps shoppers navigate to a filtered product set by making sequential attribute choices (e.g., Year → Make → Model for auto parts). Built using the Finder API with resultsPerPage=0.


Products API

An endpoint that returns full variant-level data for a single product — images, prices, SKUs, availability, variant options, and option configuration. Called when rendering a PDP or a Quick View overlay that needs complete variant details not present in search result objects.

See: Products API Reference


Quick Add to Cart

A button on a product card in a results module (search, autocomplete, category, recommendations, bundles, or chat) that adds the product to the cart without leaving the page. Fire an addToCart event when a shopper uses it. If your storefront doesn't have Quick Add to Cart for a module, skip that module's addToCart event.


quickView flag

An optional boolean (quickView: true) in the data of impression, clickThrough, and addToCart events for autocomplete, search, category, recommendations, and bundles. Set it when the interaction happened inside a quick view popup, so reporting can attribute it separately from regular page interactions.

See: Beacon.js Guide — Quick View Interactions


Recommendations

The personalized product recommendations module. Returns product sets tailored to the shopper based on browsing and purchase history. Each widget is identified by a tag matching a profile configured in the Athos Management Console.

Beacon events: render, impression, clickThrough, addToCart

See: Recommendations Tracking Guide


Recommendations API

The endpoint that returns personalized product recommendations from configured profiles.

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

Common profile tags: similar, trending, recently-viewed, bought-together, cross-sell

See: Recommendations API Reference


redirect event

A beacon event fired when a search or autocomplete query triggers a merchant-configured redirect. Fire this event and then follow the redirect in the browser. Requires responseId and redirect, the destination URL from merchandising.redirect in the API response.


Redirect (merchandising)

A URL configured by a merchant in the Athos Management Console that causes specific search queries to navigate the shopper to a different page instead of showing results (e.g., searching "sale" redirects to /pages/sale). Returned in merchandising.redirect in the API response. Your integration must both follow the redirect and fire a redirect beacon event.


render event

A beacon event fired when results are requested from the API and rendered on the page. The first event in each module's tracking sequence, except chat, which has no render event. Requires only responseId (plus tag for recommendations and bundles).


responseId

A unique ID returned by the Search, Autocomplete, Category, Finder, Recommendations, and Conversational Assistant Send APIs that ties all subsequent beacon events for that interaction back to the originating API call. Required in the data object of most beacon events.

See: Beacon.js Guide — Essential Tracking Properties


Search API

The primary endpoint for search results pages. Returns ranked products, facets, sort options, pagination, merchandising data (content for banners, redirect, elevated, removed), spell correction, and a responseId.

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

Beacon events: render, impression, clickThrough, addToCart, redirect

See: Search API Reference


Searchspring

The legacy platform that Athos Commerce succeeds. Searchspring endpoints (on searchspring.net) stay supported indefinitely, but new features are built only for the Athos v1 APIs on athoscommerce.net. Many pages in these docs apply to both, which is why they refer to your "Athos or Searchspring" account.

See: Searchspring to Athos Migration Overview


Secret Key

An authentication credential paired with your siteId for the Indexing API. Used as the password in HTTP Basic Auth (siteId:secretKey). Must be kept confidential. Contact Athos Support if you need help getting it.


Segmented Merchandising

A merchandising feature that applies campaign rules to specific shopper segments. Triggered by passing a tag in the format merch.segment/[your-tag] in the API request. Allows different product arrangements or banners for different audiences.


sessionId

A UUID that identifies a single shopping session. A session begins on the shopper's first visit or after 30 minutes of inactivity, and any tracking event resets the 30-minute timer. Stored in the athosSessionId cookie.

Scope: single visit
Duration: 30 minutes of inactivity

See: Context Object Guide


Shopify Web Pixel

A native Shopify extension included with the Athos: Unified Discovery app that automatically tracks lifecycle events (product views, cart actions, order transactions, shopper authentication) through Shopify's Customer Events API. Does not replace Beacon.js for granular interaction tracking (impressions, clicks, renders on search/autocomplete/recommendations modules). Both are typically needed for a complete Shopify integration.

See: Shopify Web Pixel Guide


shopper parameter

See athosShopperId.


shopperId

The authenticated customer identifier, included in the beacon context object when a shopper is logged in. Links events to a known customer account and enables personalized recommendations. Required on the /shopper/login endpoint and on every other event once the shopper has logged in. Not the same as userId — userId is always anonymous; shopperId is only present for authenticated users.

See: Context Object Guide


siteId

Your unique Athos or Searchspring account identifier. Required to initialize Beacon.js, included in all API endpoint URLs, and found in the Athos Management Console under My Account.


sku

Stock Keeping Unit. A product or variant catalog identifier. Included in beacon event result objects and API responses when available. Optional in all beacon events, but recommended when available.


Snap

Athos Commerce's open-source JavaScript SDK. A modular suite of libraries — client, controller, and optional UI components — that abstracts API calls, state management, filtering, pagination, and beacon tracking. Snap integrations include built-in Beacon tracking via Beacon.js; you do not need to implement it separately.

See: Choosing Your Integration Path, Snap Docs


Snap Client

The data layer of Snap (@athoscommerce/snap-client). A typed, cached JavaScript/TypeScript wrapper around the Athos APIs that also works standalone in a custom integration. Its Search and Autocomplete responses are transformed to fit Snap, so they don't match the raw API format.

See: Snap Client Guide


Snap Templates

A configuration-driven layer built on top of Snap that lets you integrate using a single SnapTemplatesConfig object rather than building a full component tree. Uses pre-built, Athos-managed Preact components and templates. Currently available through Managed Implementations only.

See: Choosing Your Integration Path


source parameter

An Autocomplete API query parameter indicating where the search query originated. Must be one of suggested (shopper selected a suggestion), historical (from search history), trending (from trending terms), or input (shopper typed and submitted directly). Used for analytics segmentation.


SPA (Single-Page Application)

A web application where navigation happens client-side without full page reloads (React, Next.js, Vue, etc.). When using Beacon.js in an SPA, call beacon.pageLoad() on each route change to generate a new pageLoadId and correctly scope events to the new view.


Suggest API

The endpoint that returns type-ahead query suggestions and spelling corrections as the shopper types. Typically called after 2+ characters with a 50ms debounce. Powers the suggestion list in the Autocomplete UI. On search bar focus (before typing), call the Trending API instead.

See: Suggest API Reference


tag

A string that identifies a specific recommendations or bundles profile configured in the Athos Management Console. Required on all recommendations and bundles beacon events, and in the recommendations API request. The tag in your event must match the tag used in the API request.

Common values: similar, trending, recently-viewed, bought-together, homepage-recommendations, pdp-bundles

The Search API's tag parameter is also used for Segmented Merchandising. Landing pages use the separate landing-page parameter.


test=true

A query parameter for Search, Autocomplete, Category, Finder, and Recommendations API requests that marks the request as a test, so it isn't processed as a real shopper interaction or counted in production analytics and reporting. Use it during development and testing.


transaction event

A beacon event fired on the order confirmation page when a shopper completes a purchase. Captures order ID, totals, line items, and geographic data. With Beacon.js, firing it also clears the stored cart state.

See: Shopping Platform Tracking Guide


Trending API

An optional endpoint that returns the most popular search queries from the past 90 days (up to 25 results). Call it on search bar focus — before the shopper has typed anything — to populate the suggestion list with popular terms.


uid

The unique identifier for a specific product variant or item. In beacon event result objects, uid is always the variant-level ID. For products without variants, uid and parentId are set to the same value. In banner payloads, uid refers to the banner uid — not a product.

See: Beacon Tracking Overview — Mapping Product Data


userId

A persistent UUID that identifies an anonymous shopper across all visits. Generated on first visit and stored in the athosUserId cookie. Regenerated only if storage is cleared or the shopper hasn't visited for 18 months. Required on every beacon event.

Different from shopperId — userId is always anonymous; shopperId is only present for authenticated users.

Scope: cross-visit
Duration: 18 months (via Beacon.js) / 1 year (raw cookie)

See: Context Object Guide


Variant

A specific product option (e.g., blue shirt in size medium). Identified by its own uid, with parentId pointing to the parent product. For products with no variants, uid and parentId share the same value. Variant-level data (images, prices, options) is returned by the Products API.


Variant-First

The Athos v1 response design where Search, Autocomplete, and personalization responses include a native variants object, so integrations can show variant attributes straight from the first API call. A key change for teams migrating from Searchspring.

See: Searchspring to Athos Migration Overview


Visual Merchandiser

The admin tool in the Athos Management Console for creating and managing merchandising campaigns. Lets teams configure campaign banners, product boosts, and A/B tests without writing code.


Did this page help you?