Custom events
Last updated: September 12, 2026
Standard events (page views, cart adds, checkout steps, orders) are tracked automatically by the web pixel. Custom events let you count anything else: a CTA click, a modal open, a form submission, scrolling past a fold, or a fact about an order.
Custom events are available on Growth and above. Your plan sets how many you can define at once.
Define an event in the admin
- In the dashboard, open Custom events from the nav
- Click Add event
- Pick a name. Lowercase letters, digits and underscores, 1 to 64 characters.
- Optionally declare the properties you want the event broken down by
- Save
Defining the event tells the pixel which event names to forward to the app. Events the pixel sees but that are not in the list are dropped, so you can call Shopify.analytics.publish() freely without ingesting noise.
Publish an event from your theme
From any theme script (snippet, section, theme-app-block):
<script>
document.querySelector('#hero-cta')?.addEventListener('click', () => {
Shopify.analytics.publish('checkout_cta_clicked', { source: 'hero' });
});
</script>
The second argument is an optional data object. The pixel forwards it with the event. Properties you declared when you created the event become breakdowns on its results, so you can see which value drove the fires.
Record an event from Shopify Flow
An event can also come from a workflow instead of from the theme. The Record split test event Flow action records a custom event for the visitor who placed an order, so something like “the order included a strap tool” can be the metric a test is judged on.
An event recorded this way is created on first use if it does not exist yet, as long as your plan still has room for it. See Shopify Flow.
Naming rules
| Rule | Why |
|---|---|
Lowercase letters, digits and underscores only (matches ^[a-z0-9_]{1,64}$) | The pixel filters anything else as malformed, and a name with a comma or a space never reaches it intact |
| Length between 1 and 64 characters | Fits a results-table column header |
| Not the name of a built-in event | A custom page_viewed would sit beside the real one on the results table with no way to tell them apart |
| Stable across deploys | Event counts attach to the name. Renaming an event starts a new series |
If a published event name does not match the rules, the pixel drops it silently. Names already taken by built-in events are refused when you create the event, with a suggestion such as page_viewed_custom.
Using a custom event as a conversion goal
When you create or edit a test, you can pick any defined custom event as the primary metric alongside standard ones (conversion rate, revenue per visitor, AOV, add-to-cart rate). The admin then tracks:
- Visitors per variant
- Conversions per variant (visitors who fired the goal at least once)
- Conversion rate
- A significance verdict against your confidence level
Conversions are counted per visitor (deduplicated). If the same visitor fires the goal three times in a session they are still counted once.
Each event is offered twice in the metric picker: as a rate per visitor, and per order. Per order is the share of orders that carry the event, and it exists for events that are facts about an order, such as the ones the Shopify Flow action records. “How many orders included a tool” is a per-order question, and a test sized on orders is judged on orders. An event that is not recorded against an order never counts toward a per-order rate.
Standard events you don’t need to define
These are tracked automatically when the pixel is active and never need to be defined as custom events. They are also reserved, so you cannot use one as a custom event name.
| Event | Fires on |
|---|---|
page_viewed | Every storefront page load |
collection_viewed | Collection page |
product_viewed | Product page |
cart_viewed | Cart page |
search_submitted | Storefront search |
product_added_to_cart | Add-to-cart action |
product_removed_from_cart | Remove-from-cart action |
checkout_started | Checkout begins |
checkout_completed | Order placed |
Orders and refunds arrive from Shopify directly rather than from the pixel, and feed the revenue metrics.
When you pick a conversion goal, this list (plus your custom events) is what appears in the dropdown.
Consent gating
The app respects Shopify’s Customer Privacy API. If a visitor has declined analytics processing or sale-of-data (CCPA), the embed does not bucket them, no cookies are set, and no events are forwarded. When the visitor later accepts consent, bucketing resumes on the next page load.
For devs: the embed reads Shopify.customerPrivacy.analyticsProcessingAllowed() and saleOfDataAllowed(), and subscribes to visitorConsentCollected to re-arm. On themes without consent management, both paths proceed and you remain responsible for your region’s compliance.
Debugging custom events
The same ?splt_debug=true flag described in storefront markup also enables console logging in the web pixel. If your event is being dropped and the console says nothing, double-check the name matches the rules above and is defined under Custom events.