Headless prerequisites

Before you call Discovery OS APIs or wire up ATS attributes in custom UI, enable the Discovery OS app embed on the storefront. The embed loads scripts, keeps the shopper session valid, and writes storefront configuration to the browser.

---

Enable the app embed

The app embed must be on for every theme where you use headless search, collections, or recommendations.

Enable app extension from embedded, see Theme customization.

---

Storefront config (localStorage)

When the app embed is enabled, Discovery OS stores storefront configuration in the browser:

Storage	localStorage
Key	pa-discoveryos-config

The value is a JSON string. Parse it once (for example JSON.parse(localStorage.getItem('pa-discoveryos-config'))) and reuse fields for API payloads, ATS attributes, and sort/facet UI.

Root fields

Field	Purpose
**websiteId**	Discovery OS website identifier for this store.
**customerId**	Shopper / device id — send on Search API requests.
**sessionId**	Session id — send on Search API requests.
**sessionDuration**	Session length hint (ms).
**lastUpdated**, **configTimestamp**	When the config was refreshed.
**facets**	Array of { field, type, label }. Use each **field** for Search **aggregations/filter**.
**sorting**	Array of { label, value, sortField }. Drive sort UI and map to Search **sort_fields**.
**recs**	Route and widget ids for ATS and recommendations (see below).

Example shape

IDs and timestamps are illustrative:

{
  "websiteId": "6de92bbf-5c81-ef11-abf3-02bf4bf6447c",
  "sorting": [
    {
      "label": "Relevance",
      "value": "relevance",
      "sortField": []
    },
    {
      "label": "Most popular",
      "value": "popularity__desc",
      "sortField": [
        {
          "popularity": {
            "order": "desc",
            "type": "number"
          }
        }
      ]
    }
  ],
  "facets": [
    {
      "field": "brand",
      "type": "string",
      "label": "Brand"
    },
    {
      "field": "filter_cat",
      "type": "string",
      "label": "Category"
    }
  ],
  "lastUpdated": 1778762758973,
  "configTimestamp": 1778762758972,
  "customerId": "f18dc7b5-b07a-4c12-9b5b-8c9f049578e8",
  "sessionId": "3e7e0272-0ac2-4dfe-b793-602532999549",
  "sessionDuration": 1800000,
  "recs": {
    "routeName": "search",
    "routeId": "bf16ffb3-8058-f011-abf3-02bf4bf6447c",
    "serpRouteId": "111-111-111-111",
    "serpWidgetId": "bbb-bbb-bbb-bbb",
    "collectionRouteId": "222-222-222-222",
    "collectionWidgetId": "ccc-ccc-ccc-ccc",
    "searchRouteId": "000-000-000-000",
    "searchWidgetId": "aaa-aaa-aaa-aaa",
    "shop": "your-store.myshopify.com",
    "source": "local_db",
    "timestamp": "2026-05-14T12:45:59.103Z"
  }
}