🔴 Phase 1 — Core · Mid-funnel signal for retargeting + ROAS optimization.

add_to_cart

When to push

After the server confirms the cart mutation (not on optimistic click). Avoids ghost events when the API fails.

quantity in the event = the amount added, not the total in the cart.

Example

async function addToCart(product, qty) {
  const res = await fetch('/api/cart/add', {
    method: 'POST',
    body: JSON.stringify({ sku: product.sku, quantity: qty })
  });
  if (!res.ok) return;

  window.dataLayer.push({ ecommerce: null });
  window.dataLayer.push({
    event: 'add_to_cart',
    ecommerce: {
      currency: 'EUR',
      value: product.price * qty,
      items: [
        {
          item_id: product.sku,
          item_name: product.name,
          item_brand: 'Biosphere',
          item_category: product.category,
          item_variant: product.variant,
          price: product.price,
          quantity: qty
        }
      ]
    }
  });
}

Parameters

Event level

Parameter	Type	Required
currency	string	required
value	number	required — price × quantity of added items
items	array	required

Item level

• item_id required
• quantity required — amount added (delta)
• price required
• Rest: recommended (see items)

Platforms

Platform	Native event
GA4	add_to_cart
Meta	AddToCart (with content_ids, contents: [{id, quantity}], value, currency)
Google Ads	Dynamic remarketing audience

Edge cases

Increasing quantity of an existing cart item

Push with the delta, not the new total.

// User clicks + on an item already at 2 → goes to 3
// Push with quantity = 1 (the delta)
{
  items: [{ item_id: 'BIO-CRM-001', quantity: 1, price: 42.00, ... }]
}

Multi-add (bundle / "shop the look")

All items in the same push:

{
  event: 'add_to_cart',
  ecommerce: {
    currency: 'EUR',
    value: 84.00,
    items: [
      { item_id: 'BIO-CRM-001', quantity: 1, price: 42.00, ... },
      { item_id: 'BIO-SER-002', quantity: 1, price: 42.00, ... }
    ]
  }
}

Pitfalls

• ❌ Push on click before API response → ghost events.
• ❌ Push total cart quantity instead of added quantity.
• ❌ value includes shipping/tax — merchandise only.