Ecommerce Events

Use the ecommerce helpers for standard journey milestones. They keep event names consistent and validate common product and money fields before delivery.

Product objectCopy Anchor Link

Reuse the same product shape throughout the journey.

var product = {
  product_id: 'sku_123',
  variant_id: 'sku_123_black',
  sku: 'BP-123-BLK',
  name: 'Everyday Backpack',
  brand: 'Northwind',
  category: 'Bags',
  price: 89.90,
  quantity: 1,
  currency: 'USD',
  url: 'https://shop.example.com/products/everyday-backpack',
  image_url: 'https://cdn.example.com/products/backpack.jpg'
};

1. Product viewedCopy Anchor Link

Call once when the product detail view becomes meaningful to the customer. For SPAs, call it after product data has loaded rather than on route change alone.

rtn.productViewed(product);

Avoid firing another product_viewed for color or image interactions unless they navigate to a distinct product or variant that you report separately.

2. Wishlist and cart actionsCopy Anchor Link

Wishlist is currently a standard custom event. Cart additions and removals use helpers.

rtn.track('product_added_to_wishlist', {
  product_id: product.product_id,
  variant_id: product.variant_id,
  name: product.name,
  price: product.price,
  currency: product.currency,
  wishlist_id: 'wishlist_primary'
});

rtn.productAddedToCart({
  ...product,
  cart_id: 'cart_456',
  quantity: 2
});

rtn.productRemovedFromCart({
  ...product,
  cart_id: 'cart_456',
  quantity: 1
});

Send the quantity changed by the action. If the customer moves from quantity 1 to 3, send quantity: 2 for the add action.

3. Cart viewedCopy Anchor Link

Send the current cart snapshot, including all lines and the total value.

var cart = {
  cart_id: 'cart_456',
  products: [
    { ...product, quantity: 2 },
    { product_id: 'sku_987', name: 'Travel Pouch', price: 24.00, quantity: 1 }
  ],
  value: 203.80,
  currency: 'USD'
};

rtn.cartViewed(cart);

value should represent the cart merchandise total at that moment. Use the same tax and shipping convention across cart, checkout, and order events.

4. Checkout startedCopy Anchor Link

Call when the customer commits to checkout, typically after clicking the checkout button or when the checkout page opens.

rtn.checkoutStarted({
  ...cart,
  coupon: 'WELCOME10'
});

For guest checkout, identify a valid email or phone when it becomes available:

rtn.identify({ email: 'guest@example.com' });

Browser-provided contact traits are treated as unverified. Your backend remains the source of truth for marketing permission and verified contact data.

5. Order completedCopy Anchor Link

Use a unique, stable order_id. Include discounts, shipping, tax, coupon, promotion, and payment method when available.

rtn.orderCompleted({
  order_id: 'order_789',
  products: cart.products,
  value: 193.42,
  revenue: 193.42,
  shipping: 0,
  tax: 17.58,
  discount: 20.38,
  currency: 'USD',
  coupon: 'WELCOME10',
  promotion_id: 'welcome_offer_2026',
  promotion_name: 'Welcome offer: 10% off',
  payment_method: 'credit_card'
});

The browser event is a fast behavioral signal. Revenue reporting should use the server-side order record, matched to this event by order_id.

Account and search eventsCopy Anchor Link

Use the built-in helpers so authentication and discovery events remain consistent.

rtn.signedUp('google');
rtn.loggedIn('email');
rtn.searched('black backpack');

Call signedUp only after account creation succeeds, loggedIn only after authentication succeeds, and searched when a query is submitted rather than on every keystroke.

Validation rulesCopy Anchor Link

RTN rejects malformed standard ecommerce events instead of storing misleading data.

Keep debug enabled in a non-production environment to see validation warnings while integrating.

Recommended journeyCopy Anchor Link

rtn.productViewed(product);
rtn.track('product_added_to_wishlist', product);
rtn.productAddedToCart(product);
rtn.cartViewed(cart);
rtn.checkoutStarted(cart);
rtn.identify('customer_123', { email: 'alex@example.com' });
rtn.orderCompleted(order);

Do not emit the entire sequence at once. Each call belongs at the real customer action in your application.