🥳Welcome to Beacon 2.0

The next generation of tracking has arrived. Beacon API v2 represents a ground-up modernization of our tracking architecture, replacing legacy Beacon and IntelliSuggest implementations with a streamlined, robust system designed for the modern web.

This migration guide is specifically crafted for current Beacon 1.0 users looking to transition to the new framework. We will walk you through the 1-to-1 changes between versions, ensuring a clear mapping of your existing events to their updated counterparts.

🚧
New to Searchspring? If you aren't currently using our legacy tracking, you can skip this migration guide and head straight to our Beacon 2.0 Documentation for a fresh implementation.

📋 Summary and Timeline

Beacon 2.0 represents a major architectural shift toward more robust, scalable analytics tracking. It is designed to handle the high-load demands of modern e-commerce while providing deeper reporting insights.

Our Migration Journey

As we look toward the future, we are phasing out our legacy systems to ensure every Searchspring client benefits from the highest security and performance standards. We are committed to working closely with you throughout the following timeline to ensure your tracking remains seamless and your data remains uninterrupted.

Phase 1: The New Standard

For teams currently building on the Athos platform, Beacon 2.0 is already the standard for all new implementations.

Phase 2: Maintenance Mode (1.0)

As of February 1st, 2026, Beacon 1.0 has officially entered Maintenance Mode. While we will continue to provide critical patches to ensure stability, all new feature development is now focused exclusively on the 2.0 framework.

Phase 3: The Critical Migration Window

The early months of 2027 mark our "Warning Mode." Between January and February 2027, it is critical for API customers to finalize their migration to 2.0. This window is designed to give your team time to validate your implementation before the legacy systems are retired.

Phase 4: End of Life (1.0)

To ensure the highest security and performance standards for all clients, we will retire the legacy infrastructure on March 31, 2027. All customers must be migrated to Beacon 2.0 by this date to ensure continued tracking and data continuity.

🌎 Global Changes

Beyond individual event updates, Beacon 2.0 introduces fundamental shifts in how our tracking infrastructure communicates with your site. These changes are designed to improve routing reliability and simplify the integration process for modern development workflows.

⚡ New Base URLs

The endpoint structure has been modernized to include explicit versioning and consistent routing. This ensures your tracking remains stable, isolated from legacy traffic, and forward-compatible. The key difference between the URLs is that siteId has been moved from the event to the endpoint.

Beacon 1.0 (Legacy): https://beacon.searchspring.io/beacon
Beacon 2.0 (Modern): https://analytics.searchspring.net/beacon/v2/{siteId}/

📦 Data Format & Native Fetch

To maximize compatibility across various browser environments and minimize "pre-flight" request overhead, every Beacon 2.0 endpoint now accepts text/plain POST data.

To ensure zero-friction integration, we recommend using Native Fetch.

🛠️ Migration at a Glance

While Beacon 2.0 provides a more powerful tracking engine, it does introduce a few breaking changes to ensure better performance and data security.

🔄
IntelliSuggest & Beacon 2.0: While we are migrating to the Beacon 2.0 framework, IntelliSuggest will continue to handle core shopper platform events. You are not required to move these specific automated events over. However, all other custom tracking, advanced reporting, and new feature integrations now require the Beacon 2.0 architecture. For the most compatible integration with Beacon 2.0 we do encourage moving over to our new Shopper platform events as soon as possible, as Intellisuggest does not currently handle sending cart/add and cart/remove events. If you are Not currently using intellisuggest, or want to migrate, check out our shopping platform events section for an endpoint overview.

Key changes include:

New URL Structure: Moving to a versioned base path including your siteId.
Simplified Logic: Removal of mandatory batching for most events.
Strict Schema: A new context + data envelope for all payloads.

🚧
IMPORTANT For a full technical breakdown of these changes and a step-by-step mapping of 1.0 logic to 2.0, please visit our Detailed Migration & Mapping Guide.

Ready to Migrate?

Now that you understand the architectural changes, the next step is mapping your existing events to the new V2 structure.

View the 1-to-1 Endpoint Migration Guide →