Cart & Checkout Events
Track cart and checkout events to attribute e-commerce revenue to Alhena AI interactions.
Use Alhena's event tracking to report e-commerce cart and checkout actions so you can attribute revenue back to your chat widget interactions.
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
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).
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.
Examples
Item added — first time a product enters the cart:
Quantity increased — user bumped quantity from 1 to 2:
Quantity decreased — user lowered quantity from 3 to 2:
Item removed — user removed the product from the cart:
sendCheckoutEvent
Report when the user completes an order.
Data properties
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:
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:
What happens behind the scenes
Company key is automatically included, so you don’t need to pass it.
Visitor fingerprints (
user_fingerprintanduser_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.
Related Pages
HTTP APIs - Server-side tracking endpoints
Revenue Attribution - How Alhena attributes revenue to AI interactions
Last updated