Sales

Cart and checkout events

How a visit's product views, cart and checkout reach Parlox, and how much each source is trusted.

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.

SourceviaHow it arrivesTrust
Your store's own cart API (Shopify, WooCommerce)platform_apiRead automatically by the browser partReported from the page: the platform answered the call, but any script on the page could send the same event
Shopify's checkout eventsshopify_pixelThe custom pixelTreated as the purchase of record on Shopify
Your server posts the orderserverpurchase() or one HTTP callConfirmed: the purchase of record
Your code calls track()apiThe browser partReported by your page
Your existing GA4 data layerdatalayerRead automatically by the browser partAs good as your GA4 setup
A raw click on a button or linknoneThe browser partShown 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 from Shopify.currency.active;
  • WooCommerce: wc-ajax=add_to_cart and the Store API's cart/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:

JavaScript
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 keepsRead from
valuevalue; a number in quotes is read as a number
currencycurrency
order_idtransaction_id
itemsThe number of entries in items (line items, not quantities)
item_idThe first entry's item_id

Good to know:

  • The data layer must be window.dataLayer. A renamed one (Tag Manager's dataLayerName) is not read.
  • GA4 events outside the list, such as view_item_list, select_item or add_to_wishlist, are ignored.
  • A purchase from 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, call parlox.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:

TypeScript
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.

EventSend it whenProperties
view_itemA product page or product detail is shownitem_id, value, currency
add_to_cartThe cart API call succeeded (not on the click)item_id, value, currency, items
remove_from_cartAn item was removeditem_id, value, currency, items
view_cartThe cart page or drawer is shownvalue, currency, items
begin_checkoutThe checkout page loadsvalue, currency, items
checkout_stepA checkout step was completed (the Shopify pixel sends contact and address)step
add_shipping_infoShipping details were acceptedvalue, currency, items
add_payment_infoPayment details were acceptedvalue, currency, items
purchaseThe order exists: the thank-you page, and from your serverorder_id, value, currency, items
searchA site search rannone
  • Money: in the browser, in major units (49.90) with a three-letter currency. 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.