# Cart & Checkout Events

Use Alhena's event tracking to report e-commerce cart and checkout actions so you can attribute revenue back to your chat widget interactions.

{% hint style="info" %}
NOTE: If you are using Shopify, the cart and checkout events are recorded by default and you do not need to follow these steps. You only need to manually report cart and checkout events for non-Shopify platforms.
{% endhint %}

## Installation

Add this tracking snippet in the section of your page:

```html
  <!-- Alhena event tracking snippet -->
  <script>
    !(function (w) {
      w._alhenaEventQueue = w._alhenaEventQueue || [];
      w.trackAlhenaEvent =
        w.trackAlhenaEvent ||
        function (method, data) {
          w._alhenaEventQueue.push({ method: method, args: data });
        };
    })(window);
  </script>
```

This snippet creates a global trackAlhenaEvent function that queues events until the widget is ready to process them, ensuring no tracking data is lost.

Make sure you've also [installed the Alhena website SDK](https://github.com/Gleen-AI/gitbook-docs/blob/main/developer-reference/website-sdk.md) first.

## sendCartEvent

Report when the user adds, removes, or updates items in their cart.

### Data properties

| Property    | Type   | Required | Description                                                                                                   |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| type        | string | Yes      | One of: `ITEM_ADDED`, `QUANTITY_INCREASED`, `QUANTITY_DECREASED`, `ITEM_REMOVED` (case-sensitive — see below) |
| productId   | string | Yes      | Your internal product identifier                                                                              |
| productName | string | Yes      | Human‑readable name                                                                                           |
| value       | number | Yes      | Price after discounts                                                                                         |
| currency    | string | Yes      | ISO 4217 currency code (e.g. "USD")                                                                           |
| quantity    | number | Yes      | Quantity after the action                                                                                     |

### Event types

You must use one of the four event type strings below — exactly as written. The widget and the Alhena backend reject any other value, and the backend ignores `QUANTITY_DECREASED` / `ITEM_REMOVED` events that don't have a matching prior `ITEM_ADDED` (or `QUANTITY_INCREASED`) for the same `productId` + visitor, to avoid recording negative revenue.

| `type` value         | Use when                                                                                   |
| -------------------- | ------------------------------------------------------------------------------------------ |
| `ITEM_ADDED`         | A product is added to the cart for the first time in this session.                         |
| `QUANTITY_INCREASED` | The quantity of a product already in the cart is increased (e.g. `1 → 2`).                 |
| `QUANTITY_DECREASED` | The quantity of a product already in the cart is decreased but not to zero (e.g. `3 → 2`). |
| `ITEM_REMOVED`       | A product is removed from the cart entirely (quantity goes to `0`).                        |

{% hint style="warning" %}
The values are `QUANTITY_INCREASED` / `QUANTITY_DECREASED` / `ITEM_REMOVED` (note the trailing `_D` / `_ED`). Strings like `ITEMS_INCREASE`, `ITEMS_DECREASE`, or `ITEMS_REMOVE` are **not** recognised and the event will be dropped.
{% endhint %}

### Examples

**Item added** — first time a product enters the cart:

```javascript
  trackAlhenaEvent('sendCartEvent', {
    type: 'ITEM_ADDED',
    productId: 'SKU-1234',
    productName: 'Black Running Shoes',
    value: 79.99,
    currency: 'USD',
    quantity: 1
  })
```

**Quantity increased** — user bumped quantity from 1 to 2:

```javascript
  trackAlhenaEvent('sendCartEvent', {
    type: 'QUANTITY_INCREASED',
    productId: 'SKU-1234',
    productName: 'Black Running Shoes',
    value: 79.99,
    currency: 'USD',
    quantity: 2
  })
```

**Quantity decreased** — user lowered quantity from 3 to 2:

```javascript
  trackAlhenaEvent('sendCartEvent', {
    type: 'QUANTITY_DECREASED',
    productId: 'SKU-1234',
    productName: 'Black Running Shoes',
    value: 79.99,
    currency: 'USD',
    quantity: 2
  })
```

**Item removed** — user removed the product from the cart:

```javascript
  trackAlhenaEvent('sendCartEvent', {
    type: 'ITEM_REMOVED',
    productId: 'SKU-1234',
    productName: 'Black Running Shoes',
    value: 79.99,
    currency: 'USD',
    quantity: 0
  })
```

## sendCheckoutEvent

Report when the user completes an order.

### Data properties

| Property  | Type   | Required | Description                                                  |
| --------- | ------ | -------- | ------------------------------------------------------------ |
| orderId   | string | No       | Your internal order ID. The same ID won't be recorded twice. |
| value     | number | Yes      | Total order value after discounts/taxes                      |
| currency  | string | Yes      | ISO 4217 currency code (e.g. "EUR")                          |
| lineItems | array  | No       | Details for each purchased item (see below)                  |

### lineItems array - each item must include:

| Property    | Type   | Required | Description                      |
| ----------- | ------ | -------- | -------------------------------- |
| productId   | string | Yes      | Your internal product identifier |
| productName | string | Yes      | Human‑readable name              |
| quantity    | number | Yes      | Quantity purchased               |
| value       | number | Yes      | Value of the product             |
| currency    | string | Yes      | ISO 4217 currency code           |

### **Example:**

```javascript
  trackAlhenaEvent('sendCheckoutEvent', {
    orderId: 'ORDER-7890',
    value: 199.97,
    currency: 'USD',
    lineItems: [
      {
        productId: 'SKU-1234',
        productName: 'Black Running Shoes',
        quantity: 1,
        value: 79.99,
        currency: 'USD'
      },
      {
        productId: 'SKU-5678',
        productName: 'Running Socks (2-pack)',
        quantity: 2,
        value: 59.99,
        currency: 'USD'
      }
    ]
  })
```

## What happens behind the scenes

* **Company key** is automatically included, so you don’t need to pass it.
* **Visitor fingerprints** (`user_fingerprint` and `user_faq_fingerprint`) are added to tie events back to unique users.
* Events will only be recorded for visitors who have interacted with the **chat widget** or the **Product FAQs** feature in their session—ensuring that only revenue driven by those interactions is attributed.
* Client‑side validation ensures all required fields are present and correctly typed.

## Troubleshooting

### No events appearing in your dashboard

* Verify the user session included interaction with the chat widget or FAQs before the cart/checkout action.
* Open Analytics > Revenue impact in the Alhena dashboard to view attributed add‑to‑cart and purchase revenue.

### Validation errors

Check the browser console for messages about missing or invalid fields and ensure you're passing correct data types.

{% hint style="info" %}
Legacy: window\.gleenWidget.sendCartEvent(data) and window\.gleenWidget.sendCheckoutEvent(data) are still supported after widget load, but trackAlhenaEvent is recommended for more reliable event capture.
{% endhint %}

## Related Pages

* [HTTP APIs](https://alhena.gitbook.io/docs/developer-reference/website-sdk/cart-checkout-events/http-apis) - Server-side tracking endpoints
* [Revenue Attribution](https://alhena.gitbook.io/docs/developer-reference/website-sdk/cart-checkout-events/revenue-attribution) - How Alhena attributes revenue to AI interactions


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alhena.gitbook.io/docs/developer-reference/website-sdk/cart-checkout-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.