Skip to main content

E-Commerce Tracking

The Joryio SDKs include built-in e-commerce tracking for product engagement, cart activity, and purchase transactions. The tracker works the same way across every platform: the same methods, the same standard event names, and the same property semantics - only the language syntax differs.

Pick your platform in any code example below; the choice syncs across the whole page. For installation and configuration, see the platform guides: Web SDK, iOS SDK, Android SDK, React Native SDK. Unity games use the iOS and Android SDKs underneath; see the Unity SDK guide.

ID Naming Convention​

Joryio uses a clear naming convention for identifiers:

Your IDDescriptionExample
productIdYour product identifier (SKU, product ID from your e-commerce platform)"SKU-12345"
orderIdYour order identifier (order number from your platform)"ORD-2024-001"
userIdYour user identifier (passed to identify())"user-123"

Use your own identifiers naturally - no special prefixes needed.

Initialize the E-Commerce Tracker​

// Get the e-commerce tracker from your SDK instance
// (joryio is the instance created with `new JoryioSDK({ sdkKey: ... })`)
const ecommerce = joryio.ecommerce({
  currency: 'USD' // Default currency for all events
});

Track Product Views & Search​

// When user views a product page
ecommerce.viewProduct({
  productId: 'SKU-12345',
  name: 'Classic Blue T-Shirt',
  price: 29.99,
  category: 'Clothing/T-Shirts',
  brand: 'Acme Apparel',
  imageUrl: 'https://example.com/images/blue-tshirt.jpg',
  url: 'https://example.com/products/blue-tshirt'
});

// When user views a category page
ecommerce.viewCategory('tshirts', 'T-Shirts');

// When user searches
ecommerce.search('blue shirts', 42); // query, result count

Track Cart Activity​

// Add item to cart
ecommerce.addToCart({
  productId: 'SKU-12345',
  name: 'Classic Blue T-Shirt',
  price: 29.99,
  quantity: 1,
  variantId: 'var-medium',
  sku: 'BTS-001-M'
}, 59.98); // Optional: current cart value

// Remove item from cart
ecommerce.removeFromCart({
  productId: 'SKU-12345',
  name: 'Classic Blue T-Shirt',
  price: 29.99
}, 1); // quantity to remove

// Update entire cart
ecommerce.updateCart([
  { productId: 'SKU-12345', name: 'Blue T-Shirt', price: 29.99, quantity: 2 },
  { productId: 'SKU-67890', name: 'Black Jeans', price: 49.99, quantity: 1 }
], 109.97); // items array, total cart value

Track Checkout Flow​

// When user starts checkout
ecommerce.startCheckout([
  { productId: 'SKU-12345', name: 'Blue T-Shirt', price: 29.99, quantity: 2 },
  { productId: 'SKU-67890', name: 'Black Jeans', price: 49.99, quantity: 1 }
], 109.97); // items, cart value

// When user adds payment info
ecommerce.addPaymentInfo('credit_card');

Track Purchases​

// When order is completed
ecommerce.purchase({
  orderId: 'ORD-2024-001',
  items: [
    {
      productId: 'SKU-12345',
      name: 'Classic Blue T-Shirt',
      price: 29.99,
      quantity: 2,
      category: 'Clothing',
      brand: 'Acme'
    },
    {
      productId: 'SKU-67890',
      name: 'Black Jeans',
      price: 49.99,
      quantity: 1
    }
  ],
  value: 109.97,
  currency: 'USD',
  shipping: 5.99,
  tax: 8.80,
  discount: 10.00,
  coupon: 'SAVE10'
});
Items Must Be Provided

The purchase() method requires you to pass the order items explicitly. The SDK does not store cart state client-side and does not pull items from the tracked cart or the server automatically. This ensures accuracy, since the order confirmation page or screen knows the exact items that were purchased.

Track Order Status Changes​

// Order shipped
ecommerce.orderFulfilled('ORD-2024-001', '1Z999AA10123456784', 'UPS');

// Order delivered
ecommerce.orderDelivered('ORD-2024-001');

// Order cancelled
ecommerce.orderCancelled('ORD-2024-001', 'Customer requested');

// Order refunded
ecommerce.orderRefunded('ORD-2024-001', 29.99, 'Product defective');

Track Wishlist & Sharing​

// Add to wishlist
ecommerce.addToWishlist({
  productId: 'SKU-12345',
  name: 'Classic Blue T-Shirt',
  price: 29.99
});

// Share product
ecommerce.shareProduct({
  productId: 'SKU-12345',
  name: 'Classic Blue T-Shirt'
}, 'facebook'); // share method

Track Coupons​

// Coupon applied
ecommerce.applyCoupon('SAVE10', 10.00, 'percentage');

// Coupon removed
ecommerce.removeCoupon('SAVE10');

Track Reviews​

// Product review submitted
ecommerce.submitReview('SKU-12345', 5, 'Great quality shirt!');

Standard E-Commerce Events​

The e-commerce tracker sends the same standard events on every platform:

Event NameDescription
Product ViewedUser views a product page
Product List ViewedUser views a category page
Products SearchedUser searches for products
Product AddedItem added to cart
Product RemovedItem removed from cart
Cart UpdatedCart contents changed
Checkout StartedUser begins checkout
Payment Info EnteredUser adds payment method
Order CompletedOrder completed
Order FulfilledOrder shipped
Order DeliveredOrder delivered
Order CancelledOrder cancelled
Order RefundedOrder refunded
Product Added to WishlistProduct added to wishlist
Product Removed from WishlistProduct removed from wishlist
Product SharedProduct shared
Coupon AppliedCoupon code applied
Coupon RemovedCoupon code removed
Product ReviewedProduct review submitted

When a store (Shopify, WooCommerce, Magento) or the Orders API sends your orders, Joryio emits Order Refunded and Order Cancelled itself - do not also call orderRefunded / orderCancelled for those orders, or each refund is recorded twice. The server events use the same order_id, refund_amount and reason keys as the trackers, so one journey condition matches both. See Refund and cancellation events.

Required arguments​

Every tracker refuses an incomplete call the same way, on every SDK: it logs a warning and sends nothing - never an event with an empty ID or a zero amount, which a revenue report would count as real. No call throws.

CallRequired
viewProduct, removeFromCart, addToWishlist, removeFromWishlistA product with a productId and a finite price
addToCartAn item with a productId and a finite price
shareProductA product as above, and a shareMethod
viewCategorycategoryId and categoryName
searchquery
cartViewed, updateCart, startCheckoutAn items array, each item with a productId and a finite price, and a finite cartValue
addPaymentInfopaymentMethod
purchaseAn orderId, an items array (it may be empty; each item as above) and a finite value
orderFulfilled, orderDelivered, orderCancelled, orderRefundedorderId
applyCoupon, removeCouponcouponCode
submitReviewproductId

An ID or label that is empty or only spaces counts as missing. An optional amount - cartValue on addToCart, shipping, tax and discount on an order, refundAmount, discountAmount - can be left out, but one you pass must be a finite number: NaN or infinity refuses the whole call instead of sending it without that amount.

Any custom properties you pass alongside follow the general rule instead: a NaN or infinite value there is dropped with a warning and the call is sent without that key - see Properties and data types.

Unity uses PascalCase names (ViewProduct, ProductId); the rules are the same.

Why use the tracker rather than track()​

Every SDK ships an e-commerce tracker, and it exists to stop you typing event names and property keys by hand.

There is deliberately no alias layer on the server. Added to Cart is not a near-miss for Product Added - it is a different event, stored verbatim, which matches no e-commerce report, no revenue attribution and no recommendation feature. The same applies to properties: an order's revenue is read from total, so an order sent with value records $0.

Neither failure produces an error. You get a plausible number, which is far harder to notice than an obviously broken one, and the tracker is how you avoid having to know any of this.

Next Steps​