Shopify Headless Getting Started

Headless mode is for stores where Shopify is the commerce backend but the storefront is Hydrogen, Next.js, Remix, or another custom frontend.

The Shopify catalog side stays the same: PSYKHE AI installs the tenant-scoped Custom Application, and the app handles catalog ingestion (what is indexed). The difference is the storefront: the Shopify theme app extension and Web Pixel are not used on the headless frontend.

What Changes In Headless Mode

• Catalog sync still runs through the Shopify Custom Application.
• Storefront UI is owned by the headless frontend, not Shopify theme blocks.
• Tracking is installed directly on the headless frontend through the Tracking API.

For the storefront, choose one of two paths:

1. PSYKHE AI UI component library - drop the provided web components into your headless frontend. You keep your routing and shell; the components render the PLP, search, and recommendation rails. This is the faster path.
2. Direct API integration - call the Recommendation API and Tracking API yourself and render your own UI. Full ownership, more work.

Integration Flow

1. Install the Shopify Application - follow the standard install. Catalog sync starts automatically.
2. Choose the frontend path - use the PSYKHE AI UI component library or call the APIs directly.
3. Configure tracking - install Tracking API/Snowplow tracking on the headless frontend and wire consent handling into the site's existing consent flow.
4. Validate the integration - confirm catalog data is available, recommendation/search surfaces render, tracking events are emitted, and the same browser identifier is passed into recommendation requests.

APIs You Will Use

• Tracking API - shopper behaviour from the headless frontend.
• Recommendation API - search, PLP, and recommendation surfaces.
• Ingestion API - only needed if you manage your own catalog feed instead of using the Shopify-managed sync (see Custom Integration).

Order Attribution Via Cart Note Attributes

In headless mode the PSYKHE AI Web Pixel is not installed, so the checkout/conversion event does not reach us directly. To back-fill order attribution from the Shopify Order webhook we already receive, attach the shopper's tracking identifiers to the order itself by adding two cart note attributes before checkout:

Both are required. Without _psykhe_duid we cannot tie the order back to the browsing session, and the conversion will not be attributed. See Tracking API getting started for how to extract each value.

The leading underscore is intentional: Shopify treats attribute keys prefixed with _ as hidden at checkout, so shoppers do not see these identifiers in the cart or order summary while they still flow through to the resulting order's note_attributes.

Storefront API example

When creating or updating the cart via the Storefront API, set them as attributes:

mutation CartAttributesUpdate(
  $cartId: ID!
  $attributes: [AttributeInput!]!
) {
  cartAttributesUpdate(cartId: $cartId, attributes: $attributes) {
    cart { id attributes { key value } }
    userErrors { field message }
  }
}

{
  "cartId": "gid://shopify/Cart/abc123",
  "attributes": [
    { "key": "_psykhe_duid", "value": "<getDomainUserId() value>" },
    { "key": "_psykhe_dsid", "value": "<getDomainUserInfo()[6] value>" }
  ]
}

Shopify carries cart attributes through to order.note_attributes on the resulting order, which the PSYKHE AI order webhook reads to emit the conversion event with the original domain_userid and domain_sessionid.