> For the complete documentation index, see [llms.txt](https://docs.elevateab.com/elevate-helpcenter/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elevateab.com/elevate-helpcenter/experiment-setup/custom-events.md).

# Custom Events

Track any action on your store as a goal metric in Elevate A/B Testing, using a custom event snippet you add to your theme and validate before launching.

***

Elevate A/B Testing measures the commerce funnel out of the box: views, add to cart, cart to checkout, checkout start, purchase, revenue, profit, and subscription share. A custom event lets you measure the steps in between.

Those built in metrics tell you whether a visitor bought. They do not tell you whether they engaged with the thing you changed. When you move a bundle selector, add a subscription toggle, or restyle a size guide, the built in funnel shows you the downstream effect without showing you whether anyone used it.

### When you need one

Use a custom event when the action you want to measure sits between landing and add to cart, or branches off the standard path.

| You want to know                                                         | Custom event                    |
| ------------------------------------------------------------------------ | ------------------------------- |
| Does the new subscribe and save toggle actually get selected             | Subscription option selected    |
| Does the quantity break or bundle selector get used                      | Bundle option selected          |
| Does the sticky add to cart bar get used more than the inline button     | Sticky add to cart clicked      |
| Does the redesigned size guide get opened, and does it reduce hesitation | Size guide opened               |
| Do visitors reach for express checkout over the standard flow            | Express checkout clicked        |
| Does anyone open the cart drawer before leaving                          | Cart drawer opened              |
| Does the product finder get completed, or abandoned halfway              | Finder completed                |
| Do out of stock visitors sign up rather than leave                       | Back in stock request submitted |

You do not need a custom event for add to cart, checkout, purchase, revenue, or subscription share of orders. Those are built in.

### How it works

A custom event is a piece of JavaScript that tells Elevate A/B Testing when a visitor performs the action. You add it to your theme once, it fires when the visitor does the thing, and from then on the event is available as a goal metric and reported per variation like any other metric.

The snippet is generated for you. You choose which element it listens to.

### Create a custom event

**Prerequisites:** access to edit theme code, or a developer who has it.

1. In the experiment's **General Info & Goal** step, select **Browse all metrics**.
2. In **Choose what to measure**, select **Add Custom Metric**.
3. Enter an **Event name**. This is what appears in your results, so name it for the action: "Subscription option selected", not "Event 1".
4. Add a **Description** if the name alone will not be clear to whoever reads the results later.
5. Copy the generated snippet with **Copy Code**.
6. Replace the placeholder selector with the element you want to track.
7. Add the snippet to your theme.
8. Trigger the action once on your storefront.
9. Return to the modal and select **Validate**.

Validation confirms Elevate A/B Testing received the event. Until it passes, you have no evidence the tracking works, and an experiment measuring an event that never fires produces a flat result that looks like a real finding.

### The snippet

The generated snippet looks like this:

```javascript
<script>
  // Fire when the visitor performs the action you want to track.
  // Replace '#your-element' with the element they interact with.
  document.querySelector('#your-element')?.addEventListener('click', () => {
    window.Shopify &&
      window.Shopify.analytics &&
      window.Shopify.analytics.publish('eab:custom_event', {
        tracking_id: 'XXXX', // Required, do not change
        event_target: 'custom_event',
      });
  });
</script>
```

**What to change:** `#your-element`. Replace it with a CSS selector matching the element the visitor interacts with, such as `.subscription-toggle` or `#sticky-atc`.

**What not to change:** `tracking_id`. It is generated per event and is how Elevate A/B Testing knows which event fired. Editing it breaks the event.

**Beyond clicks.** The generated snippet listens for a click, because that covers most cases. The `window.Shopify.analytics.publish` call is what actually records the event, so you can fire it from any condition your theme can detect: a variant selection changing, a cart drawer opening, a form submitting, or a step completing in a product finder.

### Where to put the snippet

Add it where the element exists on the page. A snippet listening for a selector that is not on the page does nothing.

If the element is added to the page after load, by an app or by your own script, a plain `querySelector` at load time will not find it. In that case attach the listener to a parent element that does exist and check the target inside the handler, or fire the publish call directly from the code that creates the element.

### Using a custom event as your goal

Once validated, the event appears in **Choose what to measure** alongside the built in metrics and can be selected as the experiment goal.

A custom event goal answers a narrower question than revenue does. That is the point, and it is also the risk.

A variation can lift the event and cost you money. Making the subscription toggle impossible to miss will raise subscription selections, and it can also add friction for the one time buyer who now has a decision to make before adding to cart. More size guide opens can mean the guide is easier to find, or that the product images stopped answering the question.

Treat a custom event as a diagnostic, not a verdict. Watch revenue per visitor alongside it, and implement a winner on the money, not the micro conversion.

### Before you launch

| Check                    | What passes                                                                   |
| ------------------------ | ----------------------------------------------------------------------------- |
| Validation passed        | The modal confirmed the event was received                                    |
| Fires on every variation | The element exists and the snippet runs on the control and every variation    |
| Fires once per action    | One action produces one event, not several                                    |
| Name is readable         | Someone reading the results in three months knows what it measures            |
| Revenue is watched too   | You know what the variation did to revenue per visitor, not only to the event |

The second one is the common failure on page and theme experiments. Variation templates and alternative themes do not automatically carry theme code added elsewhere. If the snippet only exists on the control, the variation records nothing and loses by default.

### Next steps

* Ending an Experiment for what happens to a custom event when an experiment finishes
* Metrics for the built in metric definitions
* Reading Your Results for how the goal metric decides a winner