Overview

🗺️ Find Your Integration Path

The Athos API supports several integration patterns depending on your storefront stack. Before jumping into endpoints, figure out which path fits your setup, as each one has different requirements for what you call directly vs. what's handled for you.

---

🔀 Integration Types

🔄 Migrating from Searchspring

If you're an existing Searchspring customer migrating to Athos, the endpoint structure and event tracking have changed. Don't start from scratch, use our migration guides to map your existing implementation to the new architecture.

• Searchspring to Athos Migration Guide →
• Beacon 2.0 Migration Guide →
• Both Athos Commerce and Searchspring accounts can use Beacon.js

---

⚡ API-Only (Custom Frontend)

You're building everything from scratch and calling Athos endpoints directly. This reference is your home base.

• Use Search, Autocomplete, Category, and Recommendations endpoints to fetch data
• Implement Beacon.js for event tracking
• Follow the API Integration Checklist to make sure nothing is missed

---

🫰 Snap SDK

Snap is Athos's open-source SDK that handles API requests, state management, and optional UI components for you. If you're using Snap, you won't be calling most of these endpoints directly.

• Visit the Snap documentation site for setup and configuration
• Come back here for anything Snap doesn't cover, including custom endpoints, Indexing, or Personalization edge cases
• Beacon tracking is handled by Snap automatically

---

🛍️ Shopify

If you're on Shopify, use the Shopify Web Pixel extension to handle your beacon events. The Pixel subscribes directly to Shopify Customer Events, replacing the need to manually implement Shopping Platform events for product views, cart, and orders.

• Shopify Web Pixel setup →
• Still use the Search, Autocomplete, Category, and Recommendations endpoints directly for search and discovery
• Still implement beacon events manually for search, autocomplete, and recommendations interactions

---

🏗️ Headless

You're running a headless storefront (Next.js, Hydrogen, custom React, etc.) and controlling your own rendering layer.

• Use all Search, Autocomplete, Category, and Recommendations endpoints for data
• Choose your UI approach independently; Snap components work in headless environments, or build your own
• Implement Beacon.js via NPM for tracking, as the CDN approach won't work in most SSR setups
• For server-side requests, pass the X-Forwarded-For header with the customer's IP address

---

🌐 Base URLs

Replace {siteId} with your unique Athos site ID, found in the Athos Management Console.

---

🔑 Authentication

Most API endpoints authenticate via your siteId passed as a subdomain in the base URL. No API key header is required for client-side requests.

The Indexing API uses HTTP Basic Auth, using your siteId as the username and your secretKey as the password.

https://[siteId]:[secretKey]@index-api.athoscommerce.net/api/index

---

🍪 Required Cookies

Set these on every page load before making API calls:

See Athos Cookies for full implementation details.

---

🗂️ What's in this Reference