e-Commerce Tracking

This guide explains how to add Trackboxx e-commerce tracking to any shop manually, whether you use a custom system, Shopify, Shopware, Magento or another platform. For WooCommerce, our official plugin automatically triggers all the events described here.

Basic logic: What does trackboxx('Purchase', [...])?

Before we get to the individual events, an important point to understand - experience has shown that this point is most frequently misinterpreted:

Important: trackboxx('Purchase', [...]) is no single event, but the generic call used for every e-commerce interaction. The first object in the array about his type:

• { type: 'ViewProduct' } - Product detail page
• { type: 'AddToCart' } – Product added to the basket
• { type: 'ViewCart' } – Basket page viewed
• { type: 'order' } - Order completed

The 'Purchase' in the function call simply refers to the „e-commerce“ action category and always remains the same - regardless of whether you are tracking a product view, an add-to-cart or an actual purchase.

The four e-commerce events at a glance

1. viewProduct - product detail page

Trigger: When calling up a product detail page.
Minimum data: Product name and unit price.

<script>
trackboxx('Purchase', [
  { type: ViewProduct },
  { type: 'product', name: '%%PRODUCT_NAME%%'price: 99.90 }
]);
</script>Code language: HTML, XML (xml)

Notes:

• price = Unit price of the product (numeric, dot as decimal separator).
• Optional additional fields: sku, category.
• For variants or bundles: transfer the complete variant name including attributes (e.g. „T-shirt - red, L“) so that reports are aggregated consistently.

2. AddToCart – Product added to the basket

Trigger: After a successful „Add to basket“ process - not blind on click.
Minimum data: Product name and unit price.

<script>
trackboxx('Purchase', [
  { type: AddToCart' },
  { type: 'product', name: '%%PRODUCT_NAME%%'price: 19.99 }
]);
</script>Code language: HTML, XML (xml)

Notes on timing - depending on the shop type:

• Custom shops and AJAX baskets: Trigger the event in the success callback of the add-to-basket action, not in the click handler. This prevents a tracking event from being recorded if the item never reaches the basket because of a stock check, validation issue or network error.
• Server-side shops with redirect: Trigger event once on the following page after a successful add.
• Simple button-click integrations: permitted, but only if it is ensured that the click actually leads to a successful add (e.g. button-disabled check for sold-out products).
• Deduplication: Send AddToCart only once per action - no duplication for reload or back navigation.

3. ViewCart – Basket page

Trigger: When the basket page is opened.
Minimum data: Cart total (amount). Optional: all included products as separate objects.

<script>
trackboxx('Purchase', [
  { type: ViewCart' },
  { type: 'cart', amount: 149.70 },
  { type: 'product', name: Product A'price: 99.90 },
  { type: 'product', name: Product B'price: 49.80 }
]);
</script>Code language: HTML, XML (xml)

Notes:

• amount = total basket value. Standard: Net (corresponds to the behaviour of the official WooCommerce plugin).
• If your shop works with gross prices, gross values are also permitted - the decisive factor is Consistency within an event: cart.amount and all product.price-values must be calculated on the same basis (all net or all gross).
• Send one product-object.
• The price per product corresponds to the Item total (unit price × quantity) - see section „Price logic & quantity“.

4. purchase - order completion (thank you page)

Trigger: On the order confirmation page after successful payment - exactly once per order.
Minimum data: Order ID, total amount, all products purchased.

<script>
trackboxx('Purchase', [
  { type: 'order', id: 'ORDER_ID', total: 149.70 },
  { type: 'product', name: Product A'price: 99.90 },
  { type: 'product', name: Product B'price: 49.80 }
]);
</script>Code language: HTML, XML (xml)

Optional - with voucher: One additional voucher per voucher used coupon-object.

<script>
trackboxx('Purchase', [
  { type: 'order', id: '12345', total: 149.70 },
  { type: 'coupon', name: 'SUMMER10', discount: 10.00 },
  { type: 'product', name: Product A'price: 99.90 },
  { type: 'product', name: Product B'price: 49.80 }
]);
</script>Code language: HTML, XML (xml)

Notes:

• At the purchase event there are none preceding event marker as with ViewProduct or AddToCart - the order-object identifies the event itself.
• order.id = unique order ID from the shop system.
• order.total = total value of the order (gross final amount including shipping and taxes is recommended, but must be consistent with the product.price values).
• product.price = Item total (unit price × quantity), not unit price.
• Protect against multiple firing (reload protection), e.g. via server-side flag or session marker.

Price logic & quantity

Trackboxx used no separate quantity-field. Quantities are mapped implicitly via the price. This rule is binding and should be implemented in the same way in every integration:

Example: You would like to know how often the link to your contact form is clicked on your website. If the basket contains three identical items at €19.99 each, send ViewCart and Purchase as one product-object with price: 59.97 sent - not as three separate objects and without quantity-field.

Sequence of objects in the array

For a clean, consistent integration, we recommend the following sequence of objects:

1. Event marker or. order-object (ViewProduct / AddToCart / ViewCart / order)
2. cart-object (only for ViewCart)
3. coupon-Objects (only for Purchase, if available)
4. product-objects

Best Practices

• Deduplication: Send each event only once per actual action - no double tracking for reload, back navigation or AJAX returns.
• Timing: ViewProduct and ViewCart fire on page load. AddToCart after confirmed addition. Purchase once on the thank you page.
• Prices & amounts: As Number (not a string), with a dot as decimal separator (e.g. 19.99 - not "19,99").
• Consistency: Net or gross is a decision per shop - but then consistently for cart.amount, product.price and order.total.
• Data protection: Never hand over personal data - no e-mail addresses, names, customer numbers or addresses. Respect consent.

Quick checklist per shop system

• WooCommerce: Use the official Trackboxx plugin. It triggers all four events (ViewProduct, AddToCart, ViewCart, Purchase) automatically - no manual integration necessary.
• Custom Shops: On the server, insert the product name, price and total as variables in the relevant inline script.
• Shopify: Insert snippets into the templates (product.liquid, cart.liquid, Checkout-Thank-You-Page). For AddToCart dock onto the AJAX success callback.
• Shopware / Magento: Connect the calls to the relevant theme or plugin events and hooks: product page, basket page, add-to-basket event and order-complete event.

Reference: Minimal variants

ViewProduct (minimal)

trackboxx('Purchase', [
  { type: ViewProduct },
  { type: 'product', name: Product Name 1, price: 19.99 }
]);Code language: JavaScript (javascript)

AddToCart (minimal)

trackboxx('Purchase', [
  { type: AddToCart' },
  { type: 'product', name: Product Name 1, price: 19.99 }
]);Code language: JavaScript (javascript)

ViewCart (minimal)

trackboxx('Purchase', [
  { type: ViewCart' },
  { type: 'cart', amount: 19.99 }
]);Code language: JavaScript (javascript)

Purchase (minimum)

trackboxx('Purchase', [
  { type: 'order', id: 'ORDER_ID', total: 19.99 },
  { type: 'product', name: Product Name 1, price: 19.99 }
]);Code language: JavaScript (javascript)

Brief overview: The most important rules

• trackboxx('Purchase', [...]) is a generic e-commerce call, not an event.
• The event type is in the payload (type-field of the first object), not in the function call.
• AddToCart fire after a successful add - not blindly on click.
• cart.amount as a net value by default; gross allowed, but consistent within the event.
• price = Unit price at ViewProduct / AddToCart, item total for ViewCart / Purchase.
• No separate quantity-field - quantities via the price.
• Purchase event based on { type: 'order' } without a preceding event marker.
• Prices as number with dot decimal separator, never as string.
• No personal data in the payload.