Cart & Checkout Event API

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

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.

Installation

Add this tracking snippet in the section of your page:

  <!-- 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 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"
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

Example:

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

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:

  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.

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.