Searchspring to Athos Technical Migration Guide

🚧
New to Athos? If you aren't a previous Searchspring client and are starting a fresh integration, you can skip this migration guide and head straight to our Athos V1 API Documentation.

🏁 Getting Started: Athos Migration

The Evolution: Searchspring to Athos Commerce

The transition from Searchspring to Athos Commerce is more than just a rebrand; it is a ground-up modernization of our API architecture. We are moving away from the "heavy lifting" of the legacy environment to a high-performance, Reference-Based global network. All of the features your teams need, with easy updates.

With Athos v1, we have designed a streamlined Variant-First API architecture ecosystem. By modernizing the base infrastructure and response logic, our backend now provides deeper product insights with less effort on the storefront.

Variant-First Intelligence: API responses now includes a native variants object, allowing you to display granular attributes without additional front-end processing.

📖 Table of Contents

Mapping Table: High-level architectural shifts across all endpoints.
Core Data Shifts: 1:1 cookie rename mapping from Searchspring to Athos, including the deprecation of _isuid and updated query string parameters.
Beacon 2.0 Tracking: Replacing Beacon 1.0 and Intellisuggest with the new reference-based tracking standard.
Autocomplete Module: Migrating Trending, Suggest, and Autocomplete to the versioned /v1/ paths with native Variant-First responses.
Search Module: Mapping legacy Search and Meta endpoints to the unified Athos .net domain with Variant-First result data.
Category Module: Migrating the Category (PLP) endpoint with Variant-First data mapping.
Personalization Module: Migrating Preflight and Personalized Recommendations.

🛠️ Endpoint Changes and Mappings

🌎 Global Infrastructure Shifts

The migration involves a move to versioned (v1) endpoints on the modern Athos domain.

Legacy Base: https://{siteId}.a.searchspring.io/api
Athos Base: https://{siteId}.a.athoscommerce.net/v1
Athos Personalized Recs Base: https://{siteId}.a.p13n.athoscommerce.net/v1

🗺️ Endpoint Mapping

Use this table to map legacy Searchspring paths to the new Athos v1 structure.

Module	Legacy Path (SS)	Athos v1 Path	Key Changes
Trending	`/suggest/trending`	`/trending`	Streamlined pathing.
Suggest	`/suggest/query`	`/suggest`	Unified suggest routing.
Autocomplete	`/search/autocomplete.json`	`/autocomplete`	Extension removed; native variants.
Search	`/search/search.json`	`/search`	Global high-load network.
Meta	`/meta/meta`	`/meta`	Simplified naming.
Preflight	`/personalization/preflightCache`	`/preflight`	Consolidated GET/POST.
Personalization	`/boost/{siteId}/recommend`	`/recommend`	Uses Personalize Recs Base URL.

📘
Note: All Athos Search, Autocomplete, and Recommendation responses are Variant-First, including a native variants object that replaces the need for manual data stitching on the storefront.

🍪 Core Data Shifts: Cookie Migration

Athos uses a new set of first-party cookies to manage user identity, session tracking, and personalization signals. The migration is a direct 1:1 rename, the data stored and the expiration behavior remain the same.

🗺️ Cookie Mapping

Searchspring Cookie	Athos Cookie	Expiration	Query String Parameter	Notes
`_isuid`	~~Deprecated~~	—	—	Was used for IntelliSuggest tracking. Replaced by Beacon 2.0.
`ssUserId`	`athosUserId`	1 year	—	Persistent user identifier.
`ssSessionId`	`athosSessionId`	Session	—	Expires at end of store visit.
`ssShopperId`	`athosShopperId`	Session	`shopper`	Logged-in shopper identifier.
`ssCartProducts`	`athosCartProducts`	Session	`cart`	Products currently in the shopper's cart.
`ssViewedProducts`	`athosViewedProducts`	7 years	`lastViewed`	Long-lived record of products the shopper has viewed.

⚠️ Key Changes to Note

_isuid is deprecated — this cookie was tied to the IntelliSuggest tracking system, which has been replaced by Beacon 2.0. Remove any logic that reads or writes this cookie.
Cookie names are the only change — expiration windows, session behavior, and query string parameter mappings are all identical between Searchspring and Athos.
Update cookie reads and writes across your implementation — anywhere you reference ssUserId, ssSessionId, ssShopperId, ssCartProducts, or ssViewedProducts, update to the corresponding athos* cookie name.
Beacon 2.0 context fields — athosUserId maps to context.userId and athosSessionId maps to context.sessionId in all Beacon 2.0 event payloads. See the Beacon 2.0 Migration Guide for details.

🏗️ Resource-Specific Migration

🚨 Beacon 2.0 Tracking

Beacon 2.0 is now the standard for all Athos and Searchspring implementations, and covers events for all of the modules discussed below. Although the legacy Beacon 1.0 and Intellisuggest tracking solutions are still supported for Searchspring, Athos requires Beacon 2.0. If you have already migrated to Beacon 2.0 as a part of your Searchspring implementation, you do not need any additional work done for this section.

📘
Beacon Migration: For full implementation details, including event payloads, endpoint references, and code examples, see the Beacon Tracking Guide.

🔄 Autocomplete Module

This section covers the endpoint and response changes for the three Autocomplete-related APIs: Trending, Suggest, and Autocomplete.

Endpoint Changes

API	Legacy Endpoint (Searchspring)	Athos v1 Endpoint
Trending	`https://{siteId}.a.searchspring.io/api/suggest/trending`	`https://{siteId}.a.athoscommerce.net/v1/trending`
Suggest	`https://{siteId}.a.searchspring.io/api/suggest/query`	`https://{siteId}.a.athoscommerce.net/v1/suggest`
Autocomplete	`https://{siteId}.a.searchspring.io/api/search/autocomplete.json`	`https://{siteId}.a.athoscommerce.net/v1/autocomplete`

Key structural changes to note:

The .json file extension has been removed from all endpoints. Athos paths are clean, versioned REST routes.
All three endpoints now live under the unified /v1/ namespace on the athoscommerce.net domain.
The legacy /suggest/ prefix is gone — trending and suggest are now top-level paths.

🗣️Autocomplete Response Changes

The Athos Autocomplete response is a superset of the legacy Searchspring response. Most top-level fields are preserved, but significant additions have been made to support the Variant-First architecture.

➖Fields Removed

Field	Notes
`intellisuggestData`	Replaced by the Beacon 2.0 tracking system.
`intellisuggestSignature`	Replaced by the Beacon 2.0 tracking system

➕Fields Added to `results[]`

The results array is now Variant-First. Each result object includes the following new fields:

Field	Type	Description
`parentId`	`string`	The ID of the parent product to which this variant belongs.
`responseId`	`string`	Unique identifier for the API response.
`available`	`string`	Stock availability status for the product.
`category`	`string`	The primary category the product belongs to.
`badges`	`array`	An array of `{ tag, value }` objects for promotional or status badges.
`parentImageUrl`	`string`	Image URL of the parent product, useful for display fallback logic.
`variants`	`object`	A native variants object containing full per-variant data. See below.

❗️
Note: responseIdmust be persisted for tracking purposes. See the relevant documentation for how responseId helps power your Beacon Tracking Results.

🛍️The `variants` Object

This is the most significant structural addition. Previously, variant data required manual stitching on the storefront. Athos now returns a fully resolved variants object on every result.

💻 Code Example

Searchspring Autcomplete Response: Limited data, no variants object.

{
  "pagination": {
    "totalResults": 250,
    "currentPage": 1,
    "pageSize": 24
  },
  "sorting": {
    "options": []
  },
  "results": [
    {
      "uid": "u-99120-x",
      "sku": "SKU-PRO-MAX-01",
      "intellisuggestData": "eJwNx8ENwCAMBMBmIAnB-AnLIDH_S6R6u_f0YI6as6p9",
      "intellisuggestSignature": "4f92c3a1b0e5",
      "name": "Professional Series Wireless Headphones",
      "url": "https://store.example.com/products/pro-wireless-headphones",
      "addToCartUrl": "https://store.example.com/cart/add?id=u-99120-x",
      "price": "199.99",
      "msrp": "249.00",
      "imageUrl": "https://cdn.example.com/images/pro-headphones-main.jpg",
      "thumbnailImageUrl": "https://cdn.example.com/images/thumbnails/pro-headphones-thumb.jpg",
      "rating": "4.7",
      "ratingCount": "1240",
      "description": "High-fidelity wireless audio with active noise cancellation and 40-hour battery life.",
      "stockMessage": "In Stock - Ships in 24 hours",
      "brand": "AudioTech",
      "popularity": "98"
    }
  ],
  "facets": [
    {
      "field": "category",
      "label": "Product Category",
      "type": "list",
      "multiple": "true",
      "collapse": 0,
      "facet_active": 1,
      "values": [
        {
          "active": true,
          "type": "category_filter",
          "value": "electronics",
          "low": "0",
          "high": "5000",
          "label": "Electronics",
          "count": 45
        }
      ],
      "hierarchyDelimiter": ">",
      "step": 1,
      "active": [],
      "range": [],
      "format": "text"
    }
  ],
  "breadcrumbs": [],
  "filterSummary": [],
  "merchandising": {
    "redirect": "https://store.example.com/seasonal-sale",
    "is_elevated": [],
    "elevated": [],
    "removed": [],
    "content": {
      "header": [],
      "banner": [],
      "footer": [],
      "left": [],
      "inline": []
    },
    "facets": [],
    "facetsHide": [],
    "experiments": [],
    "triggeredCampaigns": []
  },
  "didYouMean": {
    "query": "headphones",
    "highlighted": "<em>headphones</em>"
  },
  "query": {
    "matchType": "full_match",
    "original": "headphoes",
    "corrected": "headphones"
  },
  "responseId": "req-778899-abc-123"
}

💻 Code Example

New Athos Autcomplete Response: Expanded data options, fully realized native variant object.

{
  "responseId": "8f2a1c93-b4e7-4d10-8a25-99c1d072f3e8",
  "pagination": {},
  "sorting": {
    "options": [
      {
        "field": "price",
        "direction": "desc",
        "label": "Price: High to Low"
      }
    ]
  },
  "results": [
    {
      "uid": "item_v44_901",
      "parentId": "grp_shoes_55",
      "sku": "VELO-RUN-BLUE-01",
      "name": "Apex Strider X1",
      "url": "https://brandstore.example/products/apex-strider-x1",
      "addToCartUrl": "https://brandstore.example/cart/add?id=item_v44_901",
      "price": "129.95",
      "msrp": "159.00",
      "imageUrl": "https://cdn.brandstore.example/img/footwear/strider_blue.jpg",
      "thumbnailImageUrl": "https://cdn.brandstore.example/img/footwear/thumbs/strider_thumb.jpg",
      "rating": "4.6",
      "ratingCount": "312",
      "description": "Premium breathable mesh running shoe with carbon-fiber plate technology.",
      "stockMessage": "In Stock",
      "brand": "Velocity Labs",
      "popularity": "742",
      "available": "true",
      "category": "Performance Running",
      "badges": [
        {
          "tag": "top_rated",
          "value": "Top Rated"
        }
      ],
      "parentImageUrl": "https://cdn.brandstore.example/img/footwear/apex_family.jpg",
      "variants": {
        "data": [
          {
            "mappings": {
              "core": {
                "uid": "v_apex_m_11",
                "name": "Apex Strider X1 - Men's 11",
                "sku": "VELO-RUN-BLUE-01-M11",
                "price": 129.95,
                "msrp": 159.00,
                "url": "https://brandstore.example/products/apex-strider-x1?size=11",
                "imageUrl": "https://cdn.brandstore.example/img/footwear/strider_blue.jpg",
                "thumbnailImageUrl": "https://cdn.brandstore.example/img/footwear/thumbs/strider_thumb.jpg",
                "available": true
              }
            },
            "options": {
              "size": {
                "value": "11"
              }
            },
            "attributes": {
              "color_hex": "#0000FF"
            },
            "badges": [
              {
                "tag": "limited_edition",
                "value": "Limited Edition"
              }
            ],
            "optionConfig": {
              "size": {
                "type": "swatch",
                "count": 8,
                "id": 505,
                "preferences": [
                  "Standard Width"
                ]
              }
            }
          }
        ]
      }
    }
  ],
  "facets": [
    {
      "field": "brand",
      "label": "Brand",
      "type": "list",
      "multiple": "true",
      "collapse": 0,
      "facet_active": 1,
      "values": [
        {
          "active": true,
          "type": "value",
          "value": "velocity_labs",
          "low": "0",
          "high": "0",
          "label": "Velocity Labs",
          "count": 28
        }
      ],
      "hierarchyDelimiter": "|",
      "step": 0,
      "active": [
        101
      ],
      "range": [
        1
      ],
      "format": "string"
    }
  ],
  "breadcrumbs": [
    {
      "field": "category",
      "label": "Men's Shoes",
      "filterLabel": "Category",
      "filterValue": "mens-shoes",
      "removeFilters": "false",
      "removeRefineQuery": "true"
    }
  ],
  "filterSummary": [
    {
      "field": "category",
      "value": "mens-shoes",
      "label": "Men's Shoes",
      "filterLabel": "Category",
      "filterValue": "mens-shoes"
    }
  ],
  "merchandising": {
    "redirect": "none",
    "is_elevated": [
      "item_v44_901"
    ],
    "elevated": [
      "item_v44_901"
    ],
    "removed": [
      "old_legacy_001"
    ],
    "content": {
      "header": [
        "Summer Season Clearance - Save up to 40%"
      ],
      "banner": [
        "https://cdn.brandstore.example/assets/hero_banner.png"
      ],
      "footer": [
        "Free Standard Shipping on all orders over $75"
      ],
      "left": [
        "New Arrivals"
      ],
      "inline": [
        {
          "value": "Editor's Choice",
          "config": {
            "position": {
              "index": 1
            }
          }
        }
      ]
    },
    "facets": [
      "size",
      "color",
      "price"
    ],
    "facetsHide": [
      "internal_sku"
    ],
    "experiments": [
      {
        "parentCampaignId": "p_camp_99",
        "experimentId": "exp_A_B_test",
        "variationId": "var_2",
        "campaignId": "c_2024",
        "parentCampaignName": "New User Discount",
        "variationName": "Green CTA"
      }
    ],
    "triggeredCampaigns": [
      {
        "id": "t_camp_first_time",
        "title": "10% Welcome Discount",
        "type": "popup"
      }
    ]
  },
  "didYouMean": {
    "query": "strider",
    "highlighted": "Did you mean <em>strider</em>?"
  },
  "query": {
    "matchType": "fuzzy",
    "original": "stridr",
    "corrected": "strider"
  }
}

Each entry in variants.data includes:

mappings.core: Core fields configured in your AMC account (price, SKU, etc.) resolved per variant.
options : Key/value pairs for variant selectors (e.g., color, size).
attributes: Additional custom attributes defined for the variant.
badges: Variant-level badges.
optionConfig: Configuration metadata for rendering option selectors (type, display preferences, etc.).

📘
Note: Athos API responses now all return a responseId for easier data retrieval. This responseId should be preserved for beacon tracking purposes.

🔍 Search Module

This section covers the endpoint and response changes for the Search API and the supporting Meta API.

Endpoint Changes

API	Legacy Endpoint (Searchspring)	Athos v1 Endpoint
Search	`https://{siteId}.a.searchspring.io/api/search/search.json`	`https://{siteId}.a.athoscommerce.net/v1/search`
Meta	`https://{siteId}.a.searchspring.io/api/meta/meta`	`https://{siteId}.a.athoscommerce.net/v1/meta`

Key structural changes to note:

The .json file extension has been removed. Athos paths are clean, versioned REST routes.
The redundant /meta/meta double-path is simplified to /meta.
Both endpoints now live under the unified /v1/ namespace on the athoscommerce.net domain.

🗣️ Search Response Changes

The Athos Search response is a superset of the legacy Searchspring response. The core structure is preserved, with the same Variant-First additions introduced in the Autocomplete module now applied uniformly across all search surfaces.

➖ Fields Removed

Field	Notes
`intellisuggestData`	Replaced by the Beacon 2.0 tracking system.
`intellisuggestSignature`	Replaced by the Beacon 2.0 tracking system.

➕ Fields Added to `results[]`

Field	Type	Description
`parentId`	`string`	The ID of the parent product to which this variant belongs.
`responseId`	`string`	Unique identifier for the API response.
`available`	`string`	Stock availability status for the product.
`category`	`string`	The primary category the product belongs to.
`badges`	`array`	An array of `{ tag, value }` objects for promotional or status badges.
`parentImageUrl`	`string`	Image URL of the parent product, useful for display fallback logic.
`variants`	`object`	A native variants object containing full per-variant data. See below.

❗️
Note: responseIdmust be persisted for tracking purposes. See the relevant documentation for how responseId helps power your Beacon Tracking Results.

🛍️ The `variants` Object

As with Autocomplete, Athos Search returns a fully resolved variants object on every result, eliminating the need for storefront-side data stitching.

💻 Code Example

Searchspring Search Response: Limited product data, no variants object.

{
  "pagination": {},
  "sorting": {
    "options": []
  },
  "results": [
    {
      "uid": "33421-TG",
      "sku": "LIT-X1-BLK",
      "intellisuggestData": "d2h5LXdhc3RlLXRpbWUtcmVhZGluZy10aGlz",
      "intellisuggestSignature": "f9e8d7c6b5a4",
      "name": "Luminary Smart Desk Lamp",
      "url": "https://techstore.example/products/luminary-desk-lamp",
      "addToCartUrl": "https://techstore.example/cart/add?id=33421-TG",
      "price": "79.00",
      "msrp": "99.00",
      "imageUrl": "https://images.techstore.example/luminary_front.jpg",
      "thumbnailImageUrl": "https://images.techstore.example/thumbs/luminary_thumb.jpg",
      "rating": "4.9",
      "ratingCount": "412",
      "description": "Adaptive LED lighting with wireless charging base and touch controls.",
      "stockMessage": "Available for immediate dispatch",
      "brand": "NovaTech",
      "popularity": "88"
    }
  ],
  "facets": [
    {
      "field": "color",
      "label": "Color Options",
      "type": "swatch",
      "multiple": "true",
      "collapse": 1,
      "facet_active": 1,
      "values": [
        {
          "active": true,
          "type": "value",
          "value": "midnight_black",
          "low": "0",
          "high": "0",
          "label": "Midnight Black",
          "count": 12
        }
      ],
      "hierarchyDelimiter": "/",
      "step": 1,
      "active": [],
      "range": [],
      "format": "text"
    }
  ],
  "breadcrumbs": [],
  "filterSummary": [],
  "merchandising": {
    "redirect": "none",
    "is_elevated": [],
    "elevated": [],
    "removed": [],
    "content": {
      "header": [],
      "banner": [],
      "footer": [],
      "left": [],
      "inline": []
    },
    "facets": [],
    "facetsHide": [],
    "experiments": [],
    "triggeredCampaigns": []
  },
  "didYouMean": {
    "query": "desk lamp",
    "highlighted": "<em>desk lamp</em>"
  },
  "query": {
    "matchType": "exact",
    "original": "dsek lmap",
    "corrected": "desk lamp"
  },
  "responseId": "a7f2e1c4-9b3d-4e8a-b2c1-5d6e7f8a9b0c"
}

💻 Code Example

New Athos Search Response: Expanded data options, fully realized native variant object.

{
  "responseId": "x99-v2-8k22-p441",
  "pagination": {},
  "sorting": {
    "options": [
      {
        "field": "price",
        "direction": "asc",
        "label": "Price: Low to High"
      }
    ]
  },
  "results": [
    {
      "uid": "prod_trail_99",
      "parentId": "cat_outdoor_01",
      "sku": "TRL-VNT-2024",
      "name": "Summit Explorer Backpack",
      "url": "https://adventure-gear.example/products/summit-explorer",
      "addToCartUrl": "https://adventure-gear.example/cart/add?id=prod_trail_99",
      "price": "145.00",
      "msrp": "180.00",
      "imageUrl": "https://cdn.adventure-gear.example/images/backpack-blue.jpg",
      "thumbnailImageUrl": "https://cdn.adventure-gear.example/images/thumbs/backpack-blue-t.jpg",
      "rating": "4.8",
      "ratingCount": "215",
      "description": "Weather-resistant 40L hiking pack with internal frame and hydration sleeve.",
      "stockMessage": "In Stock",
      "brand": "TrailVenture",
      "popularity": "92",
      "available": "true",
      "category": "Hiking Gear",
      "badges": [
        {
          "tag": "best_seller",
          "value": "Best Seller"
        }
      ],
      "parentImageUrl": "https://cdn.adventure-gear.example/images/backpack-collection.jpg",
      "variants": {
        "data": [
          {
            "mappings": {
              "core": {
                "uid": "var_trail_99_navy",
                "name": "Summit Explorer - Navy Blue",
                "sku": "TRL-VNT-2024-NVY",
                "price": 145.0,
                "msrp": 180.0,
                "url": "https://adventure-gear.example/products/summit-explorer?color=navy",
                "imageUrl": "https://cdn.adventure-gear.example/images/backpack-navy.jpg",
                "thumbnailImageUrl": "https://cdn.adventure-gear.example/images/thumbs/backpack-navy-t.jpg",
                "available": true
              }
            },
            "options": {
              "color": {
                "value": "Navy Blue"
              }
            },
            "attributes": {
              "material": "Ripstop Nylon"
            },
            "badges": [
              {
                "tag": "sale",
                "value": "Save $35"
              }
            ],
            "optionConfig": {
              "color": {
                "type": "color_swatch",
                "count": 3,
                "id": 8821,
                "preferences": [
                  "Waterproof"
                ]
              }
            }
          }
        ]
      }
    }
  ],
  "facets": [
    {
      "field": "brand",
      "label": "Brand",
      "type": "list",
      "multiple": "true",
      "collapse": 0,
      "facet_active": 1,
      "values": [
        {
          "active": true,
          "type": "value",
          "value": "trailventure",
          "low": "0",
          "high": "0",
          "label": "TrailVenture",
          "count": 42
        }
      ],
      "hierarchyDelimiter": ">",
      "step": 0,
      "active": [
        120
      ],
      "range": [
        1
      ],
      "format": "text"
    }
  ],
  "breadcrumbs": [
    {
      "field": "category",
      "label": "Equipment",
      "filterLabel": "Category",
      "filterValue": "equipment",
      "removeFilters": "false",
      "removeRefineQuery": "true"
    }
  ],
  "filterSummary": [
    {
      "field": "category",
      "value": "equipment",
      "label": "Equipment",
      "filterLabel": "Category",
      "filterValue": "equipment"
    }
  ],
  "merchandising": {
    "redirect": "none",
    "is_elevated": [
      "prod_trail_99"
    ],
    "elevated": [
      "prod_trail_99"
    ],
    "removed": [
      "old_pack_2020"
    ],
    "content": {
      "header": [
        "Free shipping on all orders over $100"
      ],
      "banner": [
        "https://cdn.adventure-gear.example/promo/fall_sale_banner.jpg"
      ],
      "footer": [
        "Lifetime Warranty on all TrailVenture packs"
      ],
      "left": [
        "New Arrivals"
      ],
      "inline": [
        {
          "value": "Featured Product",
          "config": {
            "position": {
              "index": 4
            }
          }
        }
      ]
    },
    "facets": [
      "color",
      "price",
      "capacity"
    ],
    "facetsHide": [
      "margin_id"
    ],
    "experiments": [
      {
        "parentCampaignId": "fall_2024_promo",
        "experimentId": "ui_test_01",
        "variationId": "var_a",
        "campaignId": "camp_882",
        "parentCampaignName": "Fall Seasonal Sale",
        "variationName": "Red CTA Button"
      }
    ],
    "triggeredCampaigns": [
      {
        "id": "tc_new_member",
        "title": "Welcome to the Trail",
        "type": "email_capture"
      }
    ]
  },
  "didYouMean": {
    "query": "summit",
    "highlighted": "Did you mean <em>summit</em>?"
  },
  "query": {
    "matchType": "fuzzy",
    "original": "sumit",
    "corrected": "summit"
  }
}

Each entry in variants.data includes:

mappings.core: Core fields configured in your AMC account (price, SKU, etc.) resolved per variant.
options: Key/value pairs for variant selectors (e.g., color, size).
attributes: Additional custom attributes defined for the variant.
badges: Variant-level badges.
optionConfig: Configuration metadata for rendering option selectors (type, display preferences, etc.).

📘
Note: The Search response follows the same Variant-First pattern as Autocomplete. If you have already updated your Autocomplete result rendering to consume variants, badges, and parentId, the same logic applies here with no additional changes required.

🗂️ Category Module

This section covers the endpoint and response changes for the Category API, used to power Category-driven Product Listing Pages (PLPs).

Endpoint Changes

API	Legacy Endpoint (Searchspring)	Athos v1 Endpoint
Category	`https://{siteId}.a.searchspring.io/api/search/category.json`	`https://{siteId}.a.athoscommerce.net/v1/category`

Key structural changes to note:

The .json file extension has been removed. Athos paths are clean, versioned REST routes.
The Category endpoint moves from the legacy /search/ path prefix to its own top-level /category route, better reflecting its distinct role in powering PLPs.
The endpoint now lives under the unified /v1/ namespace on the athoscommerce.net domain.

🗣️ Category Response Changes

The Athos Category response is structurally identical to the Athos Search response. It is a superset of the legacy Searchspring Category response, with the full Variant-First result set applied uniformly, making it straightforward to share rendering logic between your search and category pages.

➖ Fields Removed

Field	Notes
`intellisuggestData`	Replaced by the Beacon 2.0 tracking system.
`intellisuggestSignature`	Replaced by the Beacon 2.0 tracking system.

➕ Fields Added to `results[]`

Field	Type	Description
`parentId`	`string`	The ID of the parent product to which this variant belongs.
`responseId`	`string`	Unique identifier for the API response
`available`	`string`	Stock availability status for the product.
`category`	`string`	The primary category the product belongs to.
`badges`	`array`	An array of `{ tag, value }` objects for promotional or status badges.
`parentImageUrl`	`string`	Image URL of the parent product, useful for display fallback logic.
`variants`	`object`	A native variants object containing full per-variant data. See below.

❗️
Note: responseIdmust be persisted for tracking purposes. See the relevant documentation for how responseId helps power your Beacon Tracking Results.

🛍️ The `variants` Object

The Category endpoint returns the same fully resolved variants object as the Search and Autocomplete endpoints. This enables consistent variant-aware rendering across all product surfaces: search results, PLPs, and typeahead from a single shared component.

💻 Code Example

Searchspring Category Response: Limited product data, no variants object.

{
  "pagination": {},
  "sorting": {
    "options": []
  },
  "results": [
    {
      "uid": "off-desk-v8",
      "sku": "DSK-WAL-092",
      "intellisuggestData": "eyJpZCI6Im9mZi1kZXNrLXY4IiwiY3BvIjoyMH0",
      "intellisuggestSignature": "d8c7b6a5e4f3",
      "name": "EvoRise Standing Desk",
      "url": "https://modernoffice.example/products/evorise-standing-desk",
      "addToCartUrl": "https://modernoffice.example/cart/add?id=off-desk-v8",
      "price": "449.00",
      "msrp": "599.00",
      "imageUrl": "https://cdn.modernoffice.example/images/desks/evorise_walnut.jpg",
      "thumbnailImageUrl": "https://cdn.modernoffice.example/images/desks/thumbs/evorise_walnut_t.jpg",
      "rating": "4.7",
      "ratingCount": "856",
      "description": "Dual-motor electric standing desk with solid walnut top and memory presets.",
      "stockMessage": "Ready to ship",
      "brand": "EvoSpace",
      "popularity": "94"
    }
  ],
  "facets": [
    {
      "field": "material",
      "label": "Surface Material",
      "type": "list",
      "multiple": "false",
      "collapse": 0,
      "facet_active": 1,
      "values": [
        {
          "active": true,
          "type": "value",
          "value": "walnut",
          "low": "0",
          "high": "0",
          "label": "Solid Walnut",
          "count": 5
        }
      ],
      "hierarchyDelimiter": ">",
      "step": 0,
      "active": [],
      "range": [],
      "format": "text"
    }
  ],
  "breadcrumbs": [],
  "filterSummary": [],
  "merchandising": {
    "redirect": "none",
    "is_elevated": [],
    "elevated": [],
    "removed": [],
    "content": {
      "header": [],
      "banner": [],
      "footer": [],
      "left": [],
      "inline": []
    },
    "facets": [],
    "facetsHide": [],
    "experiments": [],
    "triggeredCampaigns": []
  },
  "didYouMean": {
    "query": "standing desk",
    "highlighted": "<em>standing desk</em>"
  },
  "query": {
    "matchType": "exact",
    "original": "standin desk",
    "corrected": "standing desk"
  },
  "responseId": "a7f2e1c4-9b3d-4e8a-b2c1-5d6e7f8a9b0c"
}

💻 Code Example

New Athos Category Response: Expanded data options, fully realized native variant object.

{
  "responseId": "6f2d9b1a-8e3c-4a25-b1d7-4c9f0a2e3b8d",
  "pagination": {},
  "sorting": {
    "options": [
      {
        "field": "popularity",
        "direction": "desc",
        "label": "Most Popular"
      }
    ]
  },
  "results": [
    {
      "uid": "sh-cam-909",
      "parentId": "security-hub",
      "sku": "SEC-CAM-V2-BLK",
      "name": "Guardian Pro 4K Security Camera",
      "url": "https://smarthome.example/products/guardian-pro-4k",
      "addToCartUrl": "https://smarthome.example/cart/add?id=sh-cam-909",
      "price": "199.00",
      "msrp": "249.00",
      "imageUrl": "https://cdn.smarthome.example/images/cam-v2-main.jpg",
      "thumbnailImageUrl": "https://cdn.smarthome.example/images/thumbs/cam-v2-thumb.jpg",
      "rating": "4.9",
      "ratingCount": "1204",
      "description": "Ultra-HD 4K security camera with night vision and two-way audio.",
      "stockMessage": "In Stock - Ships today",
      "brand": "GuardianEye",
      "popularity": "985",
      "available": "true",
      "category": "Home Security",
      "badges": [
        {
          "tag": "editors_choice",
          "value": "Editor's Choice"
        }
      ],
      "parentImageUrl": "https://cdn.smarthome.example/images/security-hero.jpg",
      "variants": {
        "data": [
          {
            "mappings": {
              "core": {
                "uid": "sh-cam-909-b",
                "name": "Guardian Pro 4K - Midnight Black",
                "sku": "SEC-CAM-V2-BLK-01",
                "price": 199.0,
                "msrp": 249.0,
                "url": "https://smarthome.example/products/guardian-pro-4k?color=black",
                "imageUrl": "https://cdn.smarthome.example/images/cam-v2-black.jpg",
                "thumbnailImageUrl": "https://cdn.smarthome.example/images/thumbs/cam-v2-black-t.jpg",
                "available": true
              }
            },
            "options": {
              "color": {
                "value": "Midnight Black"
              }
            },
            "attributes": {
              "connectivity": "Wi-Fi 6"
            },
            "badges": [
              {
                "tag": "new_gen",
                "value": "2026 Model"
              }
            ],
            "optionConfig": {
              "color": {
                "type": "swatch",
                "count": 2,
                "id": 404,
                "preferences": [
                  "Outdoor Rated"
                ]
              }
            }
          }
        ]
      }
    }
  ],
  "facets": [
    {
      "field": "brand",
      "label": "Brand",
      "type": "list",
      "multiple": "true",
      "collapse": 0,
      "facet_active": 1,
      "values": [
        {
          "active": true,
          "type": "value",
          "value": "guardianeye",
          "low": "0",
          "high": "0",
          "label": "GuardianEye",
          "count": 15
        }
      ],
      "hierarchyDelimiter": "|",
      "step": 0,
      "active": [
        1
      ],
      "range": [
        500
      ],
      "format": "text"
    }
  ],
  "breadcrumbs": [
    {
      "field": "category",
      "label": "Home Security",
      "filterLabel": "Category",
      "filterValue": "home-security",
      "removeFilters": "false",
      "removeRefineQuery": "true"
    }
  ],
  "filterSummary": [
    {
      "field": "brand",
      "value": "guardianeye",
      "label": "GuardianEye",
      "filterLabel": "Brand",
      "filterValue": "guardianeye"
    }
  ],
  "merchandising": {
    "redirect": "none",
    "is_elevated": [
      "sh-cam-909"
    ],
    "elevated": [
      "sh-cam-909"
    ],
    "removed": [
      "old-cam-101"
    ],
    "content": {
      "header": [
        "Free 30-Day Cloud Storage Trial"
      ],
      "banner": [
        "https://cdn.smarthome.example/banners/secure_home_sale.jpg"
      ],
      "footer": [
        "2-Year Warranty Included"
      ],
      "left": [
        "Related Categories"
      ],
      "inline": [
        {
          "value": "Customer Favorite",
          "config": {
            "position": {
              "index": 1
            }
          }
        }
      ]
    },
    "facets": [
      "brand",
      "rating"
    ],
    "facetsHide": [
      "internal_code"
    ],
    "experiments": [
      {
        "parentCampaignId": "security_week",
        "experimentId": "exp_grid_v3",
        "variationId": "var_layout_b",
        "campaignId": "camp_202",
        "parentCampaignName": "Security Week Promo",
        "variationName": "Compact Grid View"
      }
    ],
    "triggeredCampaigns": [
      {
        "id": "tc_bundle_save",
        "title": "Buy 2, Save 15%",
        "type": "infobar"
      }
    ]
  },
  "didYouMean": {
    "query": "security camera",
    "highlighted": "Did you mean <em>security camera</em>?"
  },
  "query": {
    "matchType": "synonym",
    "original": "surveilance cam",
    "corrected": "security camera"
  }
}

Each entry in variants.data includes:

mappings.core: Core fields configured in your AMC account (price, SKU, etc.) resolved per variant.
options: Key/value pairs for variant selectors (e.g., color, size).
attributes: Additional custom attributes defined for the variant.
badges: Variant-level badges.
optionConfig: Configuration metadata for rendering option selectors (type, display preferences, etc.).

📘
Note: The Categoryand Search responses share an identical Athos v1 structure. If you build a shared product card component that consumes the Variant-First results[] format, it will work across both your PLP (Category) and SRP (Search) surfaces without modification.

🎯 Personalization Module

This section covers the endpoint and response changes for the Preflight and Personalized Recommendations APIs, which power personalized experiences and product bundling.

Endpoint Changes

API	Method	Legacy Endpoint (Searchspring)	Athos v1 Endpoint
Preflight	`GET`	`https://{siteId}.a.searchspring.io/api/personalization/preflightCache`	`https://{siteId}.a.athoscommerce.net/v1/preflight`
Preflight	`POST`	`https://{siteId}.a.searchspring.io/api/personalization/preflightCache`	`https://{siteId}.a.athoscommerce.net/v1/preflight`
Personalized Recs	`POST`	`https://{siteId}.a.searchspring.io/boost/{siteId}/recommend`	`https://{siteId}.a.p13n.athoscommerce.net/v1/recommend`
Personalized Recs	`GET`	`https://{siteId}.a.searchspring.io/boost/{siteId}/recommend`	`https://{siteId}.a.p13n.athoscommerce.net/v1/recommend`

Key structural changes to note:

Preflight GET and POST both migrate to /v1/preflight — path and domain update only, methods remain unchanged.
Personalized Recs moves to the dedicated P13N cluster — note the base domain is a.p13n.athoscommerce.net, not a.athoscommerce.net. Update your base URL configuration accordingly.
The legacy /boost/{siteId}/recommend path (with the redundant siteId in the path) is replaced by the clean /v1/recommend route.

🗣️ Personalized Recs Response Changes

The Searchspring recommend response was a minimal flat structure. The Athos recommend response is a fully realized Variant-First payload — consistent with the Search, Category, and Autocomplete responses with richer profile metadata and native variant support per result.

➕ Fields Added to `results[]`

Field	Type	Description
`bundleSeed`	`boolean`	Indicates whether this result is the seed product for a bundle recommendation.
`responseId`	`string`	Unique identifier for the API response
`mappings`	`object`	Core product fields (uid, name, sku, price, url, image, availability) resolved at the result level. Wraps the flat fields from the SS response.
`attributes`	`object`	Additional custom attributes for the product (e.g. `handle`, custom flags).
`parentId`	`string`	The ID of the parent product to which this variant belongs.
`parentImageUrl`	`string`	Image URL of the parent product.
`variants`	`object`	Native Variant-First object with per-variant data, options, and optionConfig.

❗️
Note: responseIdmust be persisted for tracking purposes. See the relevant documentation for how responseId helps power your Beacon Tracking Results.

🛍️ The `variants` Object

The Personalization endpoint returns the same variants structure seen across Search, Category, and Autocomplete, with two additions specific to recommendations:

💻 Code Example

Searchspring Recommend Response: Flat result structure, single object, no native variants object.

{
  "responseId": "73e9148d-b0a5-481b-90f7-117565e3b971",
  "results": [
    {
      "uid": "1198544",
      "sku": "0Y5WSW17150XS",
      "name": "Classic V-Neck Tee",
      "brand": "Essential Basics",
      "price": "24.50",
      "msrp": "35.00",
      "url": "https://example.com/products/classic-v-neck-tee",
      "imageUrl": "https://images.example.com/0Y5WSW17150XS_1.jpg",
      "thumbnailImageUrl": "https://images.example.com/0Y5WSW17150XS_thumb.jpg",
      "available": "true",
      "category": "Apparel > Tops",
      "rating": "4.5",
      "ratingCount": "12",
      "stockMessage": "In Stock",
      "popularity": "85",
      "badges": []
    }
  ],
  "merchandising": {
    "triggeredCampaigns": [
      {
        "id": "cross-sell-pdp",
        "title": "Cross Sell Recommendations",
        "type": "recommendations"
      }
    ]
  },
  "query": {
    "original": "0Y5WSW28662XS",
    "matchType": "seed-product"
  },
  "profile": {
    "tag": "cross-sell-pdp"
  }
}

💻 Code Example

New Athos Recommend Response: Array response, expanded profile, fully realized native variant object.

[
  {
    "responseId": "88ac32b538bbb2f6b0994aeada0fb67c",
    "results": [
      {
        "id": "52079573991790",
        "bundleSeed": true,
        "mappings": {
          "core": {
            "uid": "52079573991790",
            "parentId": "14725184323950",
            "name": "Studio Quarter-Zip",
            "sku": "VW1982-UQZ-BL",
            "price": 111,
            "url": "/products/studio-quarter-zip",
            "rating": "4",
            "brand": "VersaWearCo",
            "imageUrl": "https://example.com/image.png",
            "parentImageUrl": "https://example.com/parent.png",
            "available": true
          }
        },
        "attributes": {
          "handle": "studio-quarter-zip",
          "ss_is_new": 0
        },
        "variants": {
          "data": [
            {
              "mappings": {
                "core": {
                  "uid": "52079573991790",
                  "sku": "VW1982-UQZ-BL"
                }
              },
              "options": {
                "color": {
                  "value": "Black"
                }
              }
            }
          ],
          "preferences": {
            "color": "Black"
          },
          "optionConfig": {
            "color": {
              "count": 5,
              "preferences": ["Black"]
            }
          }
        }
      }
    ],
    "profile": {
      "tag": "cross-sell-bundle",
      "type": "Bundle"
    }
  }
]

Key Changes to note

variants.preferences — A key/value map of the shopper's preferred option values (e.g. { "color": "Black" }), derived from their personalization profile. Use this to pre-select the correct variant on render.
variants.optionConfig — Configuration metadata per option key (count, preference list), available at the top level of the variants object in addition to per-variant data.

Each entry in variants.data includes:

mappings.core: Core fields (uid, SKU) resolved per variant.
options: Key/value pairs for variant selectors (e.g., color, size).

📘
Note: The new profile.type field is the recommended way to identify and conditionally render different recommendation surfaces (e.g. "Bundle", "Similar", "CrossSell").

✅ Migration Complete — But You're Just Getting Started

This guide has covered the direct 1:1 migration path from Searchspring to Athos Commerce including endpoint updates, response structure changes, cookie renames, and tracking migration. If you've worked through each section, your existing integration is now running on the Athos v1 architecture.

🗺️
Explore! Athos Commerce introduces a range of new capabilities that have no equivalent in the legacy platform, features built specifically for the modern Variant-First architecture you've just migrated to. To explore what's new, head to the Athos V1 API Documentation.

🏁 Getting Started: Athos Migration

The Evolution: Searchspring to Athos Commerce

📖 Table of Contents

🛠️ Endpoint Changes and Mappings

🌎 Global Infrastructure Shifts

🗺️ Endpoint Mapping

🍪 Core Data Shifts: Cookie Migration

🗺️ Cookie Mapping

⚠️ Key Changes to Note

🏗️ Resource-Specific Migration

🚨 Beacon 2.0 Tracking

🔄 Autocomplete Module

Endpoint Changes

🗣️Autocomplete Response Changes

➖Fields Removed

➕Fields Added to results[]

🛍️The variants Object

🔍 Search Module

Endpoint Changes

🗣️ Search Response Changes

➖ Fields Removed

➕ Fields Added to results[]

🛍️ The variants Object

🗂️ Category Module

Endpoint Changes

🗣️ Category Response Changes

➖ Fields Removed

➕ Fields Added to results[]

🛍️ The variants Object

🎯 Personalization Module

Endpoint Changes

🗣️ Personalized Recs Response Changes

➕ Fields Added to results[]

🛍️ The variants Object

✅ Migration Complete — But You're Just Getting Started

➕Fields Added to `results[]`

🛍️The `variants` Object

➕ Fields Added to `results[]`

🛍️ The `variants` Object

➕ Fields Added to `results[]`

🛍️ The `variants` Object

➕ Fields Added to `results[]`

🛍️ The `variants` Object