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 is meant by 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 not a single event, but the generic call for all e-commerce interactions. The first object in the array determines which event is tracked through its type field:

• { 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: pass 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” action—not simply when the button is clicked.
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: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt 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).
• For each basket line, append a separate product-object.
• The price per product corresponds to the Item total (unit price × quantity)—see “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: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt B', price: 49.80 }
]);
</script>Code language: HTML, XML (xml)

Optional - with voucher: For each voucher used, append an additional coupon-object.

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

Notes:

• The Purchase event has no preceding event marker like those used for 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 does not use a separate quantity field. Quantities are represented implicitly through the price. This rule is binding and should be implemented consistently in every integration:

Example: Three identical items at €19.99 each in the basket are sent for ViewCart and Purchase as one product object with price: 59.97—not as three separate objects and without a 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—avoid double tracking on reload, back navigation or AJAX retries.
• 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, use 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.
• Trigger AddToCart after a successful addition to the basket—not simply when the button is clicked.
• 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.