How to Send Shopper Events to Shoply AI from a Headless Shopify Store

Shoply AI tracks shopper behavior (add to cart, checkout, product views, etc.) to improve search ranking and recommendations. On standard Shopify storefronts, this happens automatically via our Web Pixel extension . However, Shopify Web Pixels do not run on headless storefronts because they rely on Shopify’s storefront rendering engine to inject the pixel sandbox.

If you run a headless Shopify store (e.g. with Next.js, Hydrogen, or a custom frontend), you need to send these events directly from your frontend code.

Prerequisites

You have installed Shoply AI and the Shoply AI script is loaded on your storefront.

Sending an Event

Once the Shoply AI script is loaded, it exposes window.shoplyLogEvent automatically. Call it directly — no need to manage session IDs, store keys, or API endpoints yourself:


window.shoplyLogEvent(eventName, data)

The data object shape depends on the event type (see below).

Must Have Events to Support Conversion Tracking

`product_added_to_cart`

Fire this when a shopper adds a product variant to their cart.


await window.shoplyLogEvent('product_added_to_cart', {
  "cartLine": {
    "cost": {
      "totalAmount": {
        "amount": 769,
        "currencyCode": "USD"
      }
    },
    "merchandise": {
      "id": "42553607094387",  // Variant ID
      "title": "25.5 Mondo",
      "price": {
        "amount": 769,
        "currencyCode": "USD"
      },
      "product": {
        "id": "7834124058739"  // Product ID
      }
    },
    "quantity": 1
  },
  "clientId": "35214700-144e-4022-974e-fe008736e973",  // Not used
  "referrer": "https://demo.shoplyai.ai/collections/all"
})

`checkout_completed`

If you are using shopify’s native checkout, you usually don’t need this as we use web pixel events to track checkout completion automatically. However, if you have your own checkout flow, fire this when a shopper completes checkout (e.g. on your order confirmation page).


await window.shoplyLogEvent('checkout_completed', {
  "token": "8cea7db9ce551f0a8c9113a0f7f2dce0",  // Not used
  "order": {
    "id": "7251060916339",  // Shopify Order ID
    "customer": {
      "id": "9903183265907",  // Shopify Customer ID
      "isFirstOrder": true
    }
  },
  "lineItems": [
    {
      "finalLinePrice": {
        "amount": 1538,
        "currencyCode": "USD"
      },
      "quantity": 2,
      "variant": {
        "id": "42553607094387",  // Variant ID
        "title": "25.5 Mondo",
        "price": {
          "amount": 769,
          "currencyCode": "USD"
        },
        "product": {
          "id": "7834124058739"  // Product ID
        }
      }
    },
    {
      "finalLinePrice": {
        "amount": 384.93,
        "currencyCode": "USD"
      },
      "quantity": 1,
      "variant": {
        "id": "42553643958387",
        "title": "157 CM",
        "price": {
          "amount": 384.93,
          "currencyCode": "USD"
        },
        "product": {
          "id": "7834140180595"
        }
      }
    }
  ],
  "clientId": "35214700-144e-4022-974e-fe008736e973",  // Not used
  "referrer": "https://demo.shoplyai.ai/cart"
})

Need Help?

Feel free to book a meeting with us and we will help you integrate event tracking into your headless storefront.