---
title: Capture cart events (Event Protocol)
slug: o1n93466
canonical_url: https://docs.coveo.com/en/o1n93466/
collection: coveo-for-commerce
source_format: adoc
---
# Capture cart events (Event Protocol)

This article explains how to capture cart events and send the information to [Coveo Analytics](https://docs.coveo.com/en/182/).

## When to capture a cart event

Any time the content of a cart is modified by a user, the interface must log a cart event, together with the product information payload.
Cart content modifications may include adding products, removing products, or changing the quantity of existing products in the cart.
Depending on your site's design, cart events can be triggered from different places, such as:

* From a page which shows the current contents of a [visitor](https://docs.coveo.com/en/nbub9475/)’s shopping cart

* From an individual [product detail page (PDP)](https://docs.coveo.com/en/n8ad7392/)

* From a search results page

* From a [product listing page (PLP)](https://docs.coveo.com/en/m1sf3187/)

* From a [recommendation slot](https://docs.coveo.com/en/o9b80563/)

> **WARNING**
>
> cart events [don't count towards attribution](#cart-events-and-attribution).
> You must [send an additional click event](#send-an-additional-click-event) if the cart is modified directly from a search results page, [product listing page (PLP)](https://docs.coveo.com/en/m1sf3187/), or [recommendation slot](https://docs.coveo.com/en/o9b80563/).

The following image is from the cart page view of the online sporting goods store [Barca Sports](https://sports.barca.group/), which provides visitors with the ability to modify the contents of their cart by increasing or decreasing the quantity of items.

At a minimum, log the product information and the quantity added or removed in the product data payload.
Coveo calculates `quantity` as the increase or decrease in value, not the new total amount.
For example, if a client changes the quantity of an item in the cart from `1` to `2`, the quantity to pass in the cart event is `1`.

![Barca cart view | Coveo for Commerce](https://docs.coveo.com/en/assets/images/coveo-for-commerce/images/3188_images/barca-cart-event-example.png)

## Cart events and attribution

Coveo [attributes](https://docs.coveo.com/en/m7l98577/) transactions to [product discovery solutions](https://docs.coveo.com/en/o9cf0524/) by tracking [touchpoints](https://docs.coveo.com/en/o6ha0421/) along the user journey.
In a Coveo-powered commerce implementation, click events are the main [touchpoints](https://docs.coveo.com/en/o6ha0421/) used for [attribution](https://docs.coveo.com/en/m7l98577/).

Cart events don't count towards [attribution](https://docs.coveo.com/en/m7l98577/).
If your commerce implementation lets users modify the cart directly from the search results page, [product listing pages (PLPs)](https://docs.coveo.com/en/m1sf3187/), or [recommendation slots](https://docs.coveo.com/en/o9b80563/), you must [send an additional click event](#send-an-additional-click-event) along with the cart event.
This lets Coveo [attribute](https://docs.coveo.com/en/m7l98577/) transactions to the correct [solutions](https://docs.coveo.com/en/o9cf0524/).
You must send click events to track [attribution](https://docs.coveo.com/en/m7l98577/) on the [Coveo for Commerce Advanced Reports](https://docs.coveo.com/en/lbtf7260/).

For more information, see [Attribution at Coveo](https://docs.coveo.com/en/m1ae0440/).

**Example**

A user performs a query on a Coveo-powered commerce site.
They click a product to open its [product detail page (PDP)](https://docs.coveo.com/en/n8ad7392/), but they don't make a purchase and navigate away from the site.
Coveo tracks this [touchpoint](https://docs.coveo.com/en/o6ha0421/) as part of the user's journey.

Later, they revisit the site and see the same product in a [recommendation slot](https://docs.coveo.com/en/o9b80563/).
They click the product to open its [product detail page (PDP)](https://docs.coveo.com/en/n8ad7392/), creating another [touchpoint](https://docs.coveo.com/en/o6ha0421/) tracked by Coveo.
This time, the user adds the product to their cart and completes the purchase.
This product is [attributed](https://docs.coveo.com/en/m7l98577/) to the recommendation [solution](https://docs.coveo.com/en/o9cf0524/).

## How to capture a cart event

Capturing the event depends on your implementation approach.
If you're using Headless to build your commerce interfaces, you can capture the event using the Headless controllers.
Otherwise, you can use the Relay library to capture the event.

[%header,cols="3*"]
|===
2+|Implementation approach
|Tracking approach

.3+|[Headless library](https://docs.coveo.com/en/lcdf0493/)
|[Client-side rendering](https://docs.coveo.com/en/o6r70022/)
|[Managing the cart (CSR)](https://docs.coveo.com/en/o7v87042/)

|[Server-side rendering](https://docs.coveo.com/en/obif0156/)
|[Managing the cart (SSR)](https://docs.coveo.com/en/oc685394/)

|[Shopify Hydrogen](https://docs.coveo.com/en/p1oe2163/)
|[Managing the cart (Shopify Hydrogen)](https://docs.coveo.com/en/p1oe0470/)

2+|[Atomic](https://docs.coveo.com/en/lcdf0264/)
|[Managing the cart using Headless (CSR)](https://docs.coveo.com/en/o7v87042/)

2+|[Relay library](https://docs.coveo.com/en/o9je0322/)
|[Capture a cart event using Relay](#capture-a-cart-event-using-relay)

|===

### Capture a cart event using Relay

If you're using [Relay library](https://docs.coveo.com/en/o1n90002/) directly, when a user adds a product to cart, you can run the following code to capture the event and send the information to Coveo.

```js
const relay = createRelay({...}); <1>
relay.emit('ec.cartAction', { <2>
    action: 'add', <3>
    currency: 'USD',
    quantity: 1,
    product: {
        productId: 'SP03929_00014',
        name: 'Blue Bottle',
        price: 16,
    },
});
```

<1> [Initialize a Relay instance](https://docs.coveo.com/en/o1n90002/).

<2> Use the `emit` function to send an event with Relay, specifying the event name.
In this example, the value is `ec.cartAction` since it's capturing a cart event.

<3> Include the necessary event data, as outlined in the [reference documentation](https://docs.coveo.com/en/n9da0377#ec.cartaction).
Here a single product is being added to the cart.

For a detailed description of the functions offered by the library, see the [Relay documentation](https://docs.coveo.com/en/relay/latest/usage/).
> **Note**
>
> When sending events with Relay, you don't need to include the `meta` object mentioned in the Event Protocol Reference documentation, as it's automatically added by the library.

### Send an additional click event

If your Coveo-powered commerce implementation lets users send cart events directly from the search results page, [product listing pages (PLPs)](https://docs.coveo.com/en/m1sf3187/), or [recommendation slots](https://docs.coveo.com/en/o9b80563/), you must send an additional [click event](https://docs.coveo.com/en/o1n92447/) along with the cart event.

Each query has a unique `responseId` associated with it, whether it generates search results, displays product listings, or showcases recommendations.
You must include this `responseId` in the click event sent along with the cart event so that Coveo can [attribute](#cart-events-and-attribution) transactions with direct cart events to the correct [solutions](https://docs.coveo.com/en/o9cf0524/).

```js
const relay = createRelay({...});
relay.emit('ec.productClick', { <1>
    currency: 'USD',
    position: 1,
    responseId: '35009a79-1a05-49d7-b876-2b884d0f825b',
    product: {
        productId: 'SP03929_00014',
        name: 'Blue Bottle',
        price: 16,
    },
});
relay.emit('ec.cartAction', { <2>
    action: 'add',
    currency: 'USD',
    quantity: 1,
    product: {
        productId: 'SP03929_00014',
        name: 'Blue Bottle',
        price: 16,
    },
});
```

<1> Log the click event, following the [reference documentation](https://docs.coveo.com/en/n9da0377#ec.productclick).

<2> Log the cart event, following the [reference documentation](https://docs.coveo.com/en/n9da0377#ec.cartaction).

## Validating the cart event

It's important to verify that your event is valid and contains the correct payload.
Relay seamlessly integrates with _Coveo Explorer_, which can be used for event validation.

For more details on using _Coveo Explorer_ to validate events, see [Data validation](https://docs.coveo.com/en/o2170365#validating-single-events).