Cart and checkout events
How a visit's product views, cart and checkout reach Parlox, and how much each source is trusted.
On this page
Page views and detection need nothing beyond the install. To see what a visit led to (a product viewed, an add to cart, a checkout begun), Parlox has to be told by something that knows. It never guesses from button text: a button that says "Buy" can add to the cart, open the checkout or place an order, and a funnel built on guesses would be wrong in ways you could not see.
Where events come from
Every commerce event records its source in a via field, so confirmed facts and data-layer facts are never mixed.
| Source | via | How it arrives | Trust |
|---|---|---|---|
| Your store's own cart API (Shopify, WooCommerce) | platform_api | Read automatically by the browser part | Reported from the page: the platform answered the call, but any script on the page could send the same event |
| Shopify's checkout events | shopify_pixel | The custom pixel | Treated as the purchase of record on Shopify |
| Your server posts the order | server | purchase() or one HTTP call | Confirmed: the purchase of record |
Your code calls track() | api | The browser part | Reported by your page |
| Your existing GA4 data layer | datalayer | Read automatically by the browser part | As good as your GA4 setup |
| A raw click on a button or link | none | The browser part | Shown as a click, never counted as a step |
Shopify and WooCommerce: nothing to add
On Shopify and WooCommerce storefronts, add to cart is recorded with no code. The browser part watches the store's own cart API and records a successful call as add_to_cart:
- Shopify:
/cart/add.js(or/cart/add.json), with the quantity, the product id and the line price of the first line in Shopify's answer, and the store currency fromShopify.currency.active; - WooCommerce:
wc-ajax=add_to_cartand the Store API'scart/add-item, without a value.
It wraps fetch and XMLHttpRequest.open the way error and analytics tools do: your calls keep their behaviour and their return values. Only calls made with fetch or XMLHttpRequest are seen: a theme whose add-to-cart form reloads the page (a plain form post to /cart/add) is not, so call track() there, or rely on your data layer. On Shopify, checkout and purchase come from the pixel, since theme scripts cannot run on checkout.
Your GA4 data layer: nothing to add
If your store already sends GA4 ecommerce events (through Google Tag Manager, a WooCommerce or Magento GA4 plugin, or BigCommerce), the browser part reads them. It handles both shapes:
dataLayer.push({ event: "add_to_cart", ecommerce: { currency: "USD", value: 49.9, items: [{ item_id: "sku-123" }] } });
gtag("event", "begin_checkout", { currency: "USD", value: 99.8, items: [/* … */] });It reads the entries already there when it loads (up to 50 from before it started), then observes new pushes the way a second Tag Manager container does: it calls the original push, returns its result, and removes, reorders or delays nothing. gtag() writes into the same data layer, so its events are read the same way.
The event name comes from event (or the second argument of gtag("event", …)), and is read only if it is one of the names below. The rest comes from the message's ecommerce object, or the gtag call's parameters:
| Parlox keeps | Read from |
|---|---|
value | value; a number in quotes is read as a number |
currency | currency |
order_id | transaction_id |
items | The number of entries in items (line items, not quantities) |
item_id | The first entry's item_id |
Good to know:
- The data layer must be
window.dataLayer. A renamed one (Tag Manager'sdataLayerName) is not read. - GA4 events outside the list, such as
view_item_list,select_itemoradd_to_wishlist, are ignored. - A
purchasefrom the data layer is shown in the visit, but does not mark it purchased: that takes your server. - GA4's consent mode (
gtag("consent", …)) is not read. If you hold Parlox until consent, callparlox.consent(true)from the same place that grants GA4's.
Your own code: track()
On a custom stack, call track where the action has actually succeeded, the way you would call GA4 or PostHog:
import { track } from "@parlox/browser"; // with the tag: window.parlox.track(...)
track("view_item", { item_id: "sku-123", value: 49.9, currency: "USD" });
track("add_to_cart", { item_id: "sku-123", value: 49.9, currency: "USD", items: 1 });
track("begin_checkout", { value: 99.8, currency: "USD", items: 2 });With the tag, put the pre-load stub before it, so calls made before it loads are queued.
Fire on success, not on intent: after the cart request returns, not when the button is pressed.
Event names and properties
Event names are the GA4 ecommerce vocabulary.
| Event | Send it when | Properties |
|---|---|---|
view_item | A product page or product detail is shown | item_id, value, currency |
add_to_cart | The cart API call succeeded (not on the click) | item_id, value, currency, items |
remove_from_cart | An item was removed | item_id, value, currency, items |
view_cart | The cart page or drawer is shown | value, currency, items |
begin_checkout | The checkout page loads | value, currency, items |
checkout_step | A checkout step was completed (the Shopify pixel sends contact and address) | step |
add_shipping_info | Shipping details were accepted | value, currency, items |
add_payment_info | Payment details were accepted | value, currency, items |
purchase | The order exists: the thank-you page, and from your server | order_id, value, currency, items |
search | A site search ran | none |
- Money: in the browser, in major units (
49.90) with a three-lettercurrency. Parlox stores cents. From the server, in cents. - Only these properties are kept:
item_id,value,currency,items,order_id,step. Anything else is dropped, so names, emails and addresses never reach Parlox even if sent by mistake. - Any other event name is ignored.
Clicks are clicks
Every click on a real button or link is recorded with its label, for people and agents alike, and the Friction view shows where they differ most, page by page: a control people use that agents never touch is a place agents get stuck. A click that changed nothing within a second is flagged "no effect", and three or more clicks within a second in one spot are a "rage click". Clicks are shown as clicks ("clicked 'Buy now'"); they never count as a cart or purchase step. What a control means is learned separately: The control map.
Check it
Add a product to the cart in a normal browser, then open that visit in the dashboard's Visits view. Its timeline shows the add to cart with its source ("store API", "site script", "store data layer" or "Shopify"), and the visit's Reached field says Cart.