{"title":"Analytics and conversion tracking with Customer Events","slug":"tracking-customer-activity-with-events","url":"https://support.storeconnect.com/articles/tracking-customer-activity-with-events","url_markdown":"https://support.storeconnect.com/articles/tracking-customer-activity-with-events.md","subtitle":null,"summary":"Use StoreConnect Customer Events to fire analytics and advertising tracking calls, such as Google Analytics 4 and the Meta (Facebook) Pixel, when a customer adds a product to their cart or completes a purchase.","type":"Developer_Documentation","video_url":"","keywords":"customer events, current_events, process_event, analytics, conversion tracking, google analytics, ga4, meta pixel, facebook pixel, add to cart, purchase event, ecommerce tracking, liquid","last_modified":"2026-08-21T07:12:35+0000","body_markdown":"StoreConnect fires Customer Events when shoppers take actions on your store. You can read these events in Liquid and use them to send analytics and conversion tracking calls — for example, forwarding a `purchase` event to Google Analytics 4 or the Meta (Facebook) Pixel with the real order value. This guide covers the available events, how to read them, and how to connect them to your tracking providers.\n\n## Overview\n\nA Customer Event represents an action a customer performs on the store. Liquid exposes events through the global `current_events` collection, where each entry is a [CustomerEvent](customer-event-liquid-object-reference) object with a `type` and optional `event_data`.\n\nTo read an event's data you wrap it in the [`process_event`](process-event-tag-reference) block tag. The tag loads the event's properties — and, for a purchase, the full `order` object — into scope for the duration of the block, then marks the event as handled so it fires only once.\n\nYou place this Liquid in a Content Block in your store's **Head Content**, alongside the base tracking snippet for your analytics provider.\n\n## Available events\n\n| `type` | When it fires | Data available inside the block |\n|--------|---------------|---------------------------------|\n| `cart.add` | A customer adds a product to their cart | none |\n| `purchase` | A customer completes checkout and payment succeeds | the `order` object |\n\nThe `purchase` event exposes the full [Order](order-liquid-object-reference) object as `order`, so you can send accurate transaction values.\n\n## Before you begin\n\n- Install the base tracking snippet for your provider. See [Integrate Google Analytics in your store](add-your-google-analytics-code) and [Add your Facebook Pixel code](add-your-facebook-pixel-code).\n- You edit the **Head Content** through a Content Block in the StoreConnect Config app. See [Content management](content-management).\n\n## How to read and handle events\n\nLoop over `current_events`, wrap each one in `{% process_event %}`, and branch on `event.type`:\n\n\n```liquid\n\n{% for event in current_events %}\n  {% process_event event %}\n    {% if event.type == \"purchase\" %}\n      \u003c!-- order is available here --\u003e\n    {% elsif event.type == \"cart.add\" %}\n      \u003c!-- cart add --\u003e\n    {% endif %}\n  {% endprocess_event %}\n{% endfor %}\n```\n\n\n:::warning\nThe `type`, `event_data`, and `order` values are only available **inside** the `{% process_event %}...{% endprocess_event %}` block. Reading `current_events` without the `process_event` tag returns no usable data, and the event will not be marked as handled.\n:::\n\nEach event is handled exactly once. When the `process_event` block finishes, the event is marked as processed and will not appear in `current_events` on the next page load — so a purchase is not counted twice if the customer refreshes the confirmation page.\n\n## Example — Google Analytics 4\n\nAdd this to the same Content Block that holds your GA4 base snippet (`gtag`), in **Head Content**:\n\n\n```liquid\n\n{% for event in current_events %}\n  {% process_event event %}\n    {% if event.type == \"purchase\" %}\n      \u003cscript\u003e\n        gtag('event', 'purchase', {\n          transaction_id: \"{{ order.reference }}\",\n          value: {{ order.total }},\n          currency: \"{{ order.currency_code }}\",\n          tax: {{ order.total_tax }},\n          shipping: {{ order.total_shipping }}\n        });\n      \u003c/script\u003e\n    {% elsif event.type == \"cart.add\" %}\n      \u003cscript\u003e\n        gtag('event', 'add_to_cart');\n      \u003c/script\u003e\n    {% endif %}\n  {% endprocess_event %}\n{% endfor %}\n```\n\n\n## Example — Meta (Facebook) Pixel\n\nAdd this to the same Content Block that holds your Pixel base code (`fbq`):\n\n\n```liquid\n\n{% for event in current_events %}\n  {% process_event event %}\n    {% if event.type == \"purchase\" %}\n      \u003cscript\u003e\n        fbq('track', 'Purchase', {\n          value: {{ order.total }},\n          currency: \"{{ order.currency_code }}\"\n        });\n      \u003c/script\u003e\n    {% elsif event.type == \"cart.add\" %}\n      \u003cscript\u003e\n        fbq('track', 'AddToCart');\n      \u003c/script\u003e\n    {% endif %}\n  {% endprocess_event %}\n{% endfor %}\n```\n\n\n## Order values for the purchase event\n\nInside a `purchase` block, these properties are available on `order`:\n\n| Property | Description |\n|----------|-------------|\n| `order.reference` | The order reference number — use as the transaction ID |\n| `order.order_number` | The human-readable order number |\n| `order.total` | Order total, including tax |\n| `order.sub_total` | Subtotal of order items, including exclusive taxes |\n| `order.total_tax` | Total tax for the order |\n| `order.total_shipping` | Total shipping charge |\n| `order.currency_code` | The currency used for the order |\n\nSee the [Order Liquid Object Reference](order-liquid-object-reference) for the full list of available properties.\n\n## Reference\n\n- [CustomerEvent - Liquid Object Reference](customer-event-liquid-object-reference)\n- [Process Event - Liquid Tag Reference](process-event-tag-reference)\n- [Global - Liquid Object Reference](global-liquid-object-reference) — `current_events`\n- [Order - Liquid Object Reference](order-liquid-object-reference)"}