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).
region	Shopify region for this store (for example EU). Send this value on every API request as the x-shopify-region header.

Request header

Discovery OS writes region into pa-discoveryos-config. API clients must send that value on every Search, mRoute, and Recommendations request. If region is EU:

x-shopify-region: EU

See Request header in the API documentation.

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,
  "region": "EU",
  "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"
  }
}