Choosing Your Integration Path

👋 Overview

Athos Commerce offers several integration paths, each designed for different technical requirements, timelines, and levels of customization. This guide is intended for partner developers and agencies to help identify the right starting point for your storefront.

🚧

Before choosing your path, make sure you have your siteId on hand. You can find it by logging into the Athos Management Console and navigating to My Account.

⚡At a Glance

🔌 API Integration

The direct API integration path gives your team full control over every aspect of the search and discovery experience. You interact with Athos endpoints directly, constructing requests and rendering responses entirely within your own frontend code.

This is the most flexible path but also the most hands-on. Your team is responsible for building and maintaining all UI, state management, pagination, filtering logic, and beacon tracking.

Best for:

• Headless storefronts with custom frameworks
• Teams with strong frontend engineering capacity
• Storefronts with established component libraries that need to stay in place

Key responsibilities for your team:

• Cookie setup (Athos Cookies) — required before any API calls
• Implementing autocomplete, search, category, and recommendations modules
• Rendering merchandising banners and following API-driven redirects
• Implementing the full Beacon 2.0 tracking event suite

Platform notes:

• Compatible with Shopify, BigCommerce, and Magento storefronts — any platform that allows custom JavaScript and frontend code
• Shopify merchants should also review the Shopify Web Pixel for automated lifecycle event tracking

Start here: Welcome to the Athos API Reference | API Integration Checklist

🧰 API + JavaScript Libraries

Athos provides standalone JavaScript libraries that simplify specific tasks within your integration. These complement any integration path — API or Snap-based — and are particularly useful for teams who want to avoid writing tracking and analytics infrastructure from scratch.

Beacon.js

Beacon.js is a high-performance TypeScript library for sending Beacon 2.0 tracking events to the Athos API. It handles event batching, local storage management (user IDs, session IDs, cart state), and attribution tracking automatically.

You can install it via CDN for rapid integration:

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

Or via NPM for full lifecycle control in single-page applications:

npm install --save @athoscommerce/beacon

Best for: Developers with basic JavaScript knowledge building a custom API integration who need Beacon 2.0 event tracking without building the event infrastructure manually.

👍

Snap users: Snap includes built-in Beacon tracking — you do not need to implement Beacon.js separately. These instructions apply to direct API integrations only.

Shopify Web Pixel

The Shopify Web Pixel is a native component of the Athos: Unified Discovery Shopify app. It automatically tracks lifecycle events — product views, cart actions, order transactions, and shopper authentication — through Shopify's native customer events API, with no manual script tags or Liquid file edits required.

Best for: Shopify merchants on any integration path (API, Snap, or Managed) who want automated lifecycle event tracking without custom code.

❗️

The Shopify Web Pixel covers lifecycle events but does not replace Beacon.js for granular interaction tracking (clicks, impressions, renders on autocomplete, search results, and recommendation modules). Both are typically needed for a complete Shopify integration.

Start here: Beacon.js Guide | Shopify Web Pixel Guide

📦Snap SDK

Snap is Athos Commerce's open-source SDK — a modular suite of libraries designed to bridge the gap between the raw Athos APIs and your storefront's UI. Rather than building your own state management and data-fetching layer from scratch, Snap handles it for you.

Snap is organized into three layers. You can adopt one or all of them depending on how much you want Snap to own:

Best for:

• Teams with solid JavaScript/TypeScript proficiency who want Snap to handle state management
• TypeScript/JavaScript environments
• Teams building custom UIs in Vue, Angular, or vanilla JS who don't want to write their own filter and pagination logic
• Teams who want a full, ready-to-go search UI with minimal boilerplate

Tracking:

Snap includes built-in Beacon tracking via Beacon.js — you do not need to implement it separately. The Snap Controller handles event tracking, cookie management, and state synchronization automatically as part of the integration.

Platform notes:

• Snap works across any JavaScript-capable storefront, including Shopify, BigCommerce, and Magento
• On Shopify, if you are using Snap alongside the Shopify Web Pixel, the Web Pixel automatically defers to the Snap tracker's siteId if one is already present in localStorage

📘

To explore whether Snap packages are the right fit for your specific build, reach out to your designated Athos Commerce representative. You can also explore the full Snap documentation site and GitHub repository.

Start here: Snap Library Guide | Snap Docs | Snap GitHub

🎨 Snap Templates

Snap Templates (SnapTemplates from @athoscommerce/snap-preact) is a configuration-driven integration approach built on top of the Snap SDK. Rather than assembling your own component tree and controller configuration, you pass a single SnapTemplatesConfig object that covers your siteId, platform, language, currency, theme, and targets — and Snap Templates wires everything together using pre-built, Athos-managed templates and Preact components.

This makes it significantly faster to implement than standard Snap, with less boilerplate and no need to manage the full component tree yourself. You still write TypeScript/JavaScript, but the scope of what your team needs to build and maintain is much smaller.

🚧

Coming Soon Currently snap templates is only available for Athos Managed implementation. However, future development will allow for self-managed Snap Templates integration.

Compared to standard Snap:

Best for:

• Teams with basic TypeScript/JavaScript knowledge who prefer a configuration-based approach over full component development
• Teams that want a faster path to a production-ready integration without building a full component tree
• Integrations where the pre-built templates meet the storefront's design requirements
• Partners who may later need to graduate to full Snap control (see below)

Who manages the implementation?

• Athos-managed — Athos Commerce integration specialists build and maintain your Snap Templates implementation on your behalf (see Managed Implementations)

Upgrading to full Snap control: SnapHybrid

If your needs grow beyond what Snap Templates supports — custom layouts, fine-grained controller configuration, multiple search controllers, or complex targeting logic — you can transition using the SnapHybrid class. It accepts your existing SnapTemplatesConfig alongside a standard SnapConfig, preserving all your theme work, translations, and custom components while giving you full Snap control.

Start here: Snap Templates Docs | Snap Library Guide

🤝 Managed Implementations

With Managed Implementations, Athos Commerce integration specialists build and maintain your entire integration on your behalf — all implementation code and configurations — using Snap or Snap Templates. This removes the engineering burden from your team entirely.

Best for:

• Partners or agencies without dedicated frontend engineering capacity for an Athos build
• Merchants who want Athos experts to own the integration lifecycle
• Teams looking for the fastest path to a production-ready integration with no internal dev resource required

📘

To get started with a Managed Implementation, contact your Athos Commerce point of contact.

🌐 Platform-Specific Notes

Shopify

• The Athos: Unified Discovery Shopify app includes the Shopify Web Pixel for automated lifecycle event tracking with zero-touch deployment
• API and Snap integrations on Shopify are compatible with the Web Pixel — the Pixel automatically defers to the Snap tracker's siteId if both are present
• Custom API integrations on Shopify should implement both Beacon.js and the Web Pixel for full event coverage

BigCommerce

• API Integration and Snap SDK are both supported on BigCommerce storefronts
• Implement Athos Cookies and the Beacon.js tracking suite as part of your build

Magento

• API Integration and Snap SDK are both supported on Magento storefronts
• Implement Athos Cookies and the Beacon.js tracking suite as part of your build

💬 Still Not Sure?

Reach out to your Athos Commerce point of contact — they can review your storefront architecture and recommend the right path. For a full breakdown of what any custom integration requires, the API Integration Checklist is a good reference regardless of which path you choose.