Skip to content
  • There are no suggestions because the search field is empty.

Ecommerce Events

Complete guide for ecommerce events with the OIR SDK.

Table of Contents

  1. Overview
  2. Ecommerce Event Standards
  3. Product Discovery Events
  4. Cart Events
  5. Checkout Events
  6. Purchase & Refund
  7. Promotion Events
  8. Validation
  9. Best Practices

Overview

 The OIR SDK provides comprehensive ecommerce tracking following industry standards. Track the complete customer journey from product discovery to purchase.
 

Event Flow

view_item_list → view_item → add_to_cart → view_cart → begin_checkout → add_shipping_info → add_payment_info → purchase
  

Ecommerce Event Standards

To ensure consistent and reliable ecommerce tracking, follow these standards when implementing product and transaction events.

Required Properties for Ecommerce Items

All ecommerce events with items must include these required properties:

Property Type Req Description
item_id string ✅ Unique product identifier
item_name string ✅ Product name
item_variant string ✅ Product variant (color, size)

Recommended Properties

Including these properties provides richer analytics:

Property Type Description
item_category string Product category
item_brand string Product brand
price float Product price
quantity integer Quantity
currency string Currency code (e.g., 'USD')
discount float Discount amount
coupon string Applied coupon code

Standard Data Structure

{
  event: 'add_to_cart',
  ecommerce: {
    currency: 'USD',
    value: 59.98,
    items: [
      {
        item_id: 'ITM-12345',
        item_name: 'Product Name',
        item_variant: 'blue',
        item_category: 'Apparel',
        item_brand: 'Brand Name',
        price: 29.99,
        quantity: 2
      }
    ]
  }
}
 

Naming Standards

Use Consistent Property Names:

  • ✅ item_id (not product_id or productId)
  • ✅ item_name (not product_name or productName)
  • ✅ item_category (not product_category or category)
  • ✅ item_variant (not variant or product_variant)
  • ✅ item_brand (not brand or product_brand)

Event Naming:

  • ✅ view_item_list (not product_list_viewed)
  • ✅ view_item (not product_viewed)
  • ✅ add_to_cart (not cart_add or addToCart)
  • ✅ begin_checkout (not checkout_started)
  • ✅ purchase (not order_placed or transaction)

 

Product Discovery Events

Product List Viewed (view_item_list)

Track when users view a list or collection of products.

Properties:

Property Type Req Description
event string ✅ Must be view_item_list
ecommerce object ✅ Event attributes
ecommerce.product_list_id string ✅ Identifier of the list
ecommerce.product_list_name string ✅ Name of the list
ecommerce.items array ✅ Items in the list
ecommerce.items[].cart_id string ❌ Unique identifier of the shopping cart
ecommerce.items[].cart_url string ❌ URL of the shopping cart
ecommerce.items[].item_id string ✅ Identifier of the product
ecommerce.items[].item_sku string ❌ Stock Keeping Unit (SKU)
ecommerce.items[].item_name string ✅ Name of the product
ecommerce.items[].item_variant string ✅ Variant of the product
ecommerce.items[].item_category string ❌ Category of the product
ecommerce.items[].item_category2 string ❌ Second category hierarchy
ecommerce.items[].item_category3 string ❌ Third category hierarchy
ecommerce.items[].item_category4 string ❌ Fourth category hierarchy
ecommerce.items[].item_category5 string ❌ Fifth category hierarchy
ecommerce.items[].item_brand string ❌ Brand of the product
ecommerce.items[].price float ❌ Price of the product
ecommerce.items[].quantity integer ❌ Quantity of the product in the cart
ecommerce.items[].index integer ❌ Position of the product in the list
ecommerce.items[].coupon string ❌ Coupon applied to the product
ecommerce.items[].discount float ❌ Discount of the item
ecommerce.items[].url string ❌ URL of the product
ecommerce.items[].image_url string ❌ URL of the product image
ecommerce.items[].custom_attribute object ❌ Custom attribute for additional data
ecommerce.items[].item_collection string ❌ Collection of the product
ecommerce.items[].item_collection2 string ❌ Collection of the product
ecommerce.items[].item_collection3 string ❌ Collection of the product
ecommerce.items[].item_list string ❌ List of the product
ecommerce.items[].item_list2 string ❌ List of the product
ecommerce.items[].item_list3 string ❌ List of the product

Example:

_oirtrk.push([
  'event',
  {
    event: 'view_item_list',
    ecommerce: {
      product_list_id: 'related_products',
      product_list_name: 'Related products',
      items: [
        {
          cart_id: 'CART_1',
          cart_url: 'https://example.com/cart/123',
          variant_id: 'green',
          item_id: 'ITM-12345',
          item_sku: 'SKU-12345',
          item_variant: 'green',
          item_category: 'Apparel',
          item_category2: 'Adult',
          item_category3: 'Shirts',
          item_category4: 'Crew',
          item_category5: 'Short sleeve',
          item_name: 'Sample',
          price: 10.01,
          quantity: 1,
          index: 1,
          coupon: 'SUMMER_FUN',
          discount: 2.22,
          url: 'https://example.com/product/123',
          image_url: 'https://example.com/product/123/image',
          item_list_id: 'related_products',
          item_list_name: 'Related products',
          item_collection: 'Shirt',
          item_collection2: 'Adult',
          item_collection3: 'Summer',
          item_list: 'Shirt',
          item_list2: 'Adult',
          item_list3: 'Seasonal',
        },
      ],
    },
  },
]);
 

Product Viewed (view_item)

Track when a user views a product detail page.

Properties:

Property Type Req Description
event string ✅ Must be view_item
ecommerce object ✅ Event attributes
ecommerce.currency string ❌ Currency code
ecommerce.value float ❌ Monetary value
ecommerce.items array ✅ Items viewed
ecommerce.items[].cart_id string ❌ Unique identifier of the shopping cart
ecommerce.items[].cart_url string ❌ URL of the shopping cart
ecommerce.items[].item_id string ✅ Identifier of the product
ecommerce.items[].item_sku string ❌ Stock Keeping Unit (SKU)
ecommerce.items[].item_name string ✅ Name of the product
ecommerce.items[].item_variant string ✅ Variant of the product
ecommerce.items[].item_category string ❌ Category of the product
ecommerce.items[].item_category2 string ❌ Second category hierarchy
ecommerce.items[].item_category3 string ❌ Third category hierarchy
ecommerce.items[].item_category4 string ❌ Fourth category hierarchy
ecommerce.items[].item_category5 string ❌ Fifth category hierarchy
ecommerce.items[].item_brand string ❌ Brand of the product
ecommerce.items[].price float ❌ Price of the product
ecommerce.items[].quantity integer ❌ Quantity of the product in the cart
ecommerce.items[].index integer ❌ Position of the product in the list
ecommerce.items[].coupon string ❌ Coupon applied to the product
ecommerce.items[].discount float ❌ Discount of the item
ecommerce.items[].url string ❌ URL of the product
ecommerce.items[].image_url string ❌ URL of the product image
ecommerce.items[].custom_attribute object ❌ Custom attribute for additional data
ecommerce.items[].item_collection string ❌ Collection of the product
ecommerce.items[].item_collection2 string ❌ Collection of the product
ecommerce.items[].item_collection3 string ❌ Collection of the product
ecommerce.items[].item_list string ❌ List of the product
ecommerce.items[].item_list2 string ❌ List of the product
ecommerce.items[].item_list3 string ❌ List of the product

Example:

_oirtrk.push([
  'event',
  {
    event: 'view_item',
    ecommerce: {
      currency: 'USD',
      value: 19.99,
      items: [
        {
          cart_id: 'CART_1',
          cart_url: 'https://example.com/cart/123',
          variant_id: 'green',
          item_id: 'ITM-12345',
          item_sku: 'SKU-12345',
          item_variant: 'green',
          item_category: 'Apparel',
          item_category2: 'Adult',
          item_category3: 'Shirts',
          item_category4: 'Crew',
          item_category5: 'Short sleeve',
          item_name: 'Sample',
          price: 19.99,
          quantity: 1,
          index: 1,
          url: 'https://example.com/product/123',
          image_url: 'https://example.com/product/123/image',
          item_list_id: 'related_products',
          item_list_name: 'Related products',
          item_collection: 'Shirt',
          item_collection2: 'Adult',
          item_collection3: 'Summer',
          item_list: 'Shirt',
          item_list2: 'Adult',
          item_list3: 'Seasonal',
        },
      ],
    },
  },
]);
 

Select Item (select_item)

Track when a user selects an item from a list.

Properties:

Property Type Req Description
event string ✅ Must be select_item
ecommerce object ✅ Event attributes
ecommerce.item_list_id string ❌ List identifier
ecommerce.item_list_name string ❌ List name
ecommerce.items array ✅ Selected items
ecommerce.items[].cart_id string ❌ Unique identifier of the shopping cart
ecommerce.items[].cart_url string ❌ URL of the shopping cart
ecommerce.items[].item_id string ✅ Identifier of the product
ecommerce.items[].item_sku string ❌ Stock Keeping Unit (SKU)
ecommerce.items[].item_name string ✅ Name of the product
ecommerce.items[].item_variant string ✅ Variant of the product
ecommerce.items[].item_category string ❌ Category of the product
ecommerce.items[].item_category2 string ❌ Second category hierarchy
ecommerce.items[].item_category3 string ❌ Third category hierarchy
ecommerce.items[].item_category4 string ❌ Fourth category hierarchy
ecommerce.items[].item_category5 string ❌ Fifth category hierarchy
ecommerce.items[].item_brand string ❌ Brand of the product
ecommerce.items[].price float ❌ Price of the product
ecommerce.items[].quantity integer ❌ Quantity of the product in the cart
ecommerce.items[].index integer ❌ Position of the product in the list
ecommerce.items[].coupon string ❌ Coupon applied to the product
ecommerce.items[].discount float ❌ Discount of the item
ecommerce.items[].url string ❌ URL of the product
ecommerce.items[].image_url string ❌ URL of the product image
ecommerce.items[].custom_attribute object ❌ Custom attribute for additional data
ecommerce.items[].item_collection string ❌ Collection of the product
ecommerce.items[].item_collection2 string ❌ Collection of the product
ecommerce.items[].item_collection3 string ❌ Collection of the product
ecommerce.items[].item_list string ❌ List of the product
ecommerce.items[].item_list2 string ❌ List of the product
ecommerce.items[].item_list3 string ❌ List of the product

Example:

_oirtrk.push([
  'event',
  {
    event: 'select_item',
    ecommerce: {
      item_list_id: 'search_results',
      item_list_name: 'Search Results',
      items: [
        {
          cart_id: 'CART_1',
          cart_url: 'https://example.com/cart/123',
          variant_id: 'green',
          item_id: 'ITM-12345',
          item_sku: 'SKU-12345',
          item_variant: 'green',
          item_category: 'Apparel',
          item_name: 'Sample',
          price: 10.01,
          quantity: 1,
          index: 2,
          url: 'https://example.com/product/123',
          image_url: 'https://example.com/product/123/image',
          item_collection: 'Shirt',
          item_collection2: 'Adult',
          item_collection3: 'Summer',
          item_list: 'Shirt',
          item_list2: 'Adult',
          item_list3: 'Seasonal',
        },
      ],
    },
  },
]);
 

Cart Events

Cart Viewed (view_cart)

Track when users view their shopping cart.

Properties:

Property Type Req Description
event string ✅ Must be view_cart
ecommerce object ✅ Event attributes
ecommerce.currency string ❌ Currency of price, discount
ecommerce.value float ✅ Sum of (price * quantity) for all items
ecommerce.items array ✅ Items attributes
ecommerce.items[].cart_id string ✅ Unique identifier of the shopping cart
ecommerce.items[].cart_url string ✅ URL of the shopping cart
ecommerce.items[].item_id string ✅ Identifier of the product
ecommerce.items[].item_sku string ❌ Stock Keeping Unit (SKU)
ecommerce.items[].item_name string ✅ Name of the product
ecommerce.items[].item_variant string ✅ Variant of the product
ecommerce.items[].item_category string ❌ Category of the product
ecommerce.items[].item_category2 string ❌ Second category hierarchy
ecommerce.items[].item_category3 string ❌ Third category hierarchy
ecommerce.items[].item_category4 string ❌ Fourth category hierarchy
ecommerce.items[].item_category5 string ❌ Fifth category hierarchy
ecommerce.items[].item_brand string ❌ Brand of the product
ecommerce.items[].price float ❌ Price of the product
ecommerce.items[].quantity integer ❌ Quantity of the product in the cart
ecommerce.items[].index integer ❌ Position of the product in the list
ecommerce.items[].coupon string ❌ Coupon applied to the product
ecommerce.items[].discount float ❌ Discount of the item
ecommerce.items[].url string ❌ URL of the product
ecommerce.items[].image_url string ❌ URL of the product image
ecommerce.items[].custom_attribute object ❌ Custom attribute for additional data
ecommerce.items[].item_collection string ❌ Collection of the product
ecommerce.items[].item_collection2 string ❌ Collection of the product
ecommerce.items[].item_collection3 string ❌ Collection of the product
ecommerce.items[].item_list string ❌ List of the product
ecommerce.items[].item_list2 string ❌ List of the product
ecommerce.items[].item_list3 string ❌ List of the product

Example:

_oirtrk.push([
  'event',
  {
    event: 'view_cart',
    ecommerce: {
      currency: 'USD',
      value: 49.98,
      items: [
        {
          cart_id: 'CART_001',
          cart_url: 'https://example.com/cart/001',
          item_id: 'TSHIRT_BLUE_M',
          item_name: 'Blue Cotton T-Shirt',
          item_variant: 'blue',
          item_category: 'Apparel',
          item_category2: 'Men',
          item_category3: 'Tops',
          item_category4: 'T-Shirts',
          item_category5: 'Short Sleeve',
          item_collection: 'Summer Collection',
          item_collection2: 'Casual',
          item_list: 'Featured Products',
          item_list2: 'New Arrivals',
          item_brand: 'FashionCo',
          price: 24.99,
          quantity: 2,
          index: 1,
          coupon: 'SUMMER20',
          discount: 5.0,
          url: 'https://example.com/product/tshirt-blue',
          image_url: 'https://example.com/images/tshirt-blue.jpg',
          custom_attribute: {
            size: 'M',
            color: 'Blue',
          },
        },
      ],
    },
  },
]);
 

Product Added To Cart (add_to_cart)

Track when users add products to their shopping cart.

Properties:

Property Type Req Description
event string ✅ Must be add_to_cart
ecommerce object ✅ Event attributes
ecommerce.currency string ❌ Currency
ecommerce.value float ✅ Event value
ecommerce.items array ✅ Items added
ecommerce.items[].cart_id string ✅ Unique identifier of the shopping cart
ecommerce.items[].cart_url string ✅ URL of the shopping cart
ecommerce.items[].item_id string ✅ Identifier of the product
ecommerce.items[].item_sku string ❌ Stock Keeping Unit (SKU)
ecommerce.items[].item_name string ✅ Name of the product
ecommerce.items[].item_variant string ✅ Variant of the product
ecommerce.items[].item_category string ❌ Category of the product
ecommerce.items[].item_category2 string ❌ Second category hierarchy
ecommerce.items[].item_category3 string ❌ Third category hierarchy
ecommerce.items[].item_category4 string ❌ Fourth category hierarchy
ecommerce.items[].item_category5 string ❌ Fifth category hierarchy
ecommerce.items[].item_brand string ❌ Brand of the product
ecommerce.items[].price float ❌ Price of the product
ecommerce.items[].quantity integer ❌ Quantity of the product in the cart
ecommerce.items[].index integer ❌ Position of the product in the list
ecommerce.items[].coupon string ❌ Coupon applied to the product
ecommerce.items[].discount float ❌ Discount of the item
ecommerce.items[].url string ❌ URL of the product
ecommerce.items[].image_url string ❌ URL of the product image
ecommerce.items[].custom_attribute object ❌ Custom attribute for additional data
ecommerce.items[].item_collection string ❌ Collection of the product
ecommerce.items[].item_collection2 string ❌ Collection of the product
ecommerce.items[].item_collection3 string ❌ Collection of the product
ecommerce.items[].item_list string ❌ List of the product
ecommerce.items[].item_list2 string ❌ List of the product
ecommerce.items[].item_list3 string ❌ List of the product

Example:

_oirtrk.push([
  'event',
  {
    event: 'add_to_cart',
    ecommerce: {
      currency: 'USD',
      value: 79.99,
      items: [
        {
          cart_id: 'CART_002',
          cart_url: 'https://example.com/cart/002',
          item_id: 'JEANS_DARK_L',
          item_name: 'Dark Wash Jeans',
          item_variant: 'dark-wash',
          item_category: 'Apparel',
          item_category2: 'Men',
          item_category3: 'Bottoms',
          item_category4: 'Jeans',
          item_category5: 'Straight Fit',
          item_collection: 'Denim Collection',
          item_collection2: 'Classic',
          item_list: 'Best Sellers',
          item_list2: 'Denim',
          item_brand: 'DenimCo',
          price: 79.99,
          quantity: 1,
          index: 1,
          coupon: 'NEWCUSTOMER',
          discount: 10.0,
          url: 'https://example.com/product/jeans-dark',
          image_url: 'https://example.com/images/jeans-dark.jpg',
          custom_attribute: {
            size: 'L',
            fit: 'Straight',
          },
        },
      ],
    },
  },
]);
 

Product Removed From Cart (remove_from_cart)

Track when users remove products from their shopping cart.

Properties:

Property Type Req Description
event string ✅ Must be remove_from_cart
ecommerce object ✅ Event attributes
ecommerce.currency string ❌ Currency
ecommerce.value float ✅ Event value
ecommerce.items array ✅ Items removed
ecommerce.items[].cart_id string ✅ Unique identifier of the shopping cart
ecommerce.items[].cart_url string ✅ URL of the shopping cart
ecommerce.items[].item_id string ✅ Identifier of the product
ecommerce.items[].item_sku string ❌ Stock Keeping Unit (SKU)
ecommerce.items[].item_name string ✅ Name of the product
ecommerce.items[].item_variant string ✅ Variant of the product
ecommerce.items[].item_category string ❌ Category of the product
ecommerce.items[].item_category2 string ❌ Second category hierarchy
ecommerce.items[].item_category3 string ❌ Third category hierarchy
ecommerce.items[].item_category4 string ❌ Fourth category hierarchy
ecommerce.items[].item_category5 string ❌ Fifth category hierarchy
ecommerce.items[].item_brand string ❌ Brand of the product
ecommerce.items[].price float ❌ Price of the product
ecommerce.items[].quantity integer ❌ Quantity of the product in the cart
ecommerce.items[].index integer ❌ Position of the product in the list
ecommerce.items[].coupon string ❌ Coupon applied to the product
ecommerce.items[].discount float ❌ Discount of the item
ecommerce.items[].url string ❌ URL of the product
ecommerce.items[].image_url string ❌ URL of the product image
ecommerce.items[].custom_attribute object ❌ Custom attribute for additional data
ecommerce.items[].item_collection string ❌ Collection of the product
ecommerce.items[].item_collection2 string ❌ Collection of the product
ecommerce.items[].item_collection3 string ❌ Collection of the product
ecommerce.items[].item_list string ❌ List of the product
ecommerce.items[].item_list2 string ❌ List of the product
ecommerce.items[].item_list3 string ❌ List of the product

Example:

_oirtrk.push([
  'event',
  {
    event: 'remove_from_cart',
    ecommerce: {
      currency: 'USD',
      value: 129.99,
      items: [
        {
          cart_id: 'CART_003',
          cart_url: 'https://example.com/cart/003',
          item_id: 'SNEAKERS_WHITE_10',
          item_name: 'White Running Sneakers',
          item_variant: 'white',
          item_category: 'Footwear',
          item_category2: 'Men',
          item_category3: 'Athletic',
          item_category4: 'Running',
          item_category5: 'Daily Training',
          item_collection: 'Athletic Collection',
          item_collection2: 'Running',
          item_list: 'Sale Items',
          item_list2: 'Footwear',
          item_brand: 'SportBrand',
          price: 129.99,
          quantity: 1,
          index: 1,
          coupon: 'SPORT20',
          discount: 26.0,
          url: 'https://example.com/product/sneakers-white',
          image_url: 'https://example.com/images/sneakers-white.jpg',
          custom_attribute: {
            size: '10',
            color: 'White',
          },
        },
      ],
    },
  },
]);
 

Checkout Events

Checkout Started (begin_checkout)

Track when users begin the checkout process.

Properties:

Property Type Req Description
event string ✅ Must be begin_checkout
ecommerce object ✅ Event attributes
ecommerce.checkout_id string ❌ Checkout identifier
ecommerce.checkout_url string ❌ Checkout URL
ecommerce.value float ✅ Total value
ecommerce.currency string ❌ Currency
ecommerce.shipping float ❌ Shipping cost
ecommerce.tax float ❌ Tax amount
ecommerce.discount float ❌ Discount
ecommerce.coupon string ❌ Coupon
ecommerce.items array ✅ Items in checkout
ecommerce.items[].cart_id string ❌ Unique identifier of the shopping cart
ecommerce.items[].cart_url string ❌ URL of the shopping cart
ecommerce.items[].item_id string ✅ Identifier of the product
ecommerce.items[].item_sku string ❌ Stock Keeping Unit (SKU)
ecommerce.items[].item_name string ✅ Name of the product
ecommerce.items[].item_variant string ✅ Variant of the product
ecommerce.items[].item_category string ❌ Category of the product
ecommerce.items[].item_category2 string ❌ Second category hierarchy
ecommerce.items[].item_category3 string ❌ Third category hierarchy
ecommerce.items[].item_category4 string ❌ Fourth category hierarchy
ecommerce.items[].item_category5 string ❌ Fifth category hierarchy
ecommerce.items[].item_brand string ❌ Brand of the product
ecommerce.items[].price float ❌ Price of the product
ecommerce.items[].quantity integer ❌ Quantity of the product in the cart
ecommerce.items[].index integer ❌ Position of the product in the list
ecommerce.items[].coupon string ❌ Coupon applied to the product
ecommerce.items[].discount float ❌ Discount of the item
ecommerce.items[].url string ❌ URL of the product
ecommerce.items[].image_url string ❌ URL of the product image
ecommerce.items[].custom_attribute object ❌ Custom attribute for additional data
ecommerce.items[].item_collection string ❌ Collection of the product
ecommerce.items[].item_collection2 string ❌ Collection of the product
ecommerce.items[].item_collection3 string ❌ Collection of the product
ecommerce.items[].item_list string ❌ List of the product
ecommerce.items[].item_list2 string ❌ List of the product
ecommerce.items[].item_list3 string ❌ List of the product

Example:

_oirtrk.push([
  'event',
  {
    event: 'begin_checkout',
    ecommerce: {
      checkout_id: 'CHECKOUT_001',
      checkout_url: 'https://example.com/checkout/001',
      total_items: 3,
      value: 234.97,
      revenue: 234.97,
      shipping: 9.99,
      tax: 19.6,
      discount: 15.0,
      currency: 'USD',
      coupon: 'WELCOME15',
      items: [
        {
          cart_id: 'CART_004',
          cart_url: 'https://example.com/cart/004',
          item_id: 'JACKET_BLACK_M',
          item_name: 'Black Leather Jacket',
          item_variant: 'black',
          item_category: 'Apparel',
          item_category2: 'Men',
          item_category3: 'Outerwear',
          item_category4: 'Jackets',
          item_category5: 'Leather',
          item_collection: 'Premium Collection',
          item_collection2: 'Leather',
          item_list: 'Featured',
          item_list2: 'Outerwear',
          item_brand: 'LeatherCo',
          price: 199.99,
          quantity: 1,
          index: 1,
          coupon: 'WELCOME15',
          discount: 15.0,
          url: 'https://example.com/product/jacket-black',
          image_url: 'https://example.com/images/jacket-black.jpg',
          custom_attribute: {
            size: 'M',
            material: 'Leather',
          },
        },
      ],
    },
  },
]);
 

Shipping Info Added (add_shipping_info)

Track when users submit their shipping details.

Properties:

Property Type Req Description
event string ✅ Must be add_shipping_info
ecommerce object ✅ Event attributes
ecommerce.order_id string ✅ Order identifier
ecommerce.value float ✅ Order total
ecommerce.shipping float ❌ Shipping cost
ecommerce.shipping_tier string ✅ Selected shipping tier
ecommerce.currency string ❌ Currency
ecommerce.coupon string ❌ Coupon
ecommerce.items array ✅ Items
ecommerce.items[].cart_id string ❌ Unique identifier of the shopping cart
ecommerce.items[].cart_url string ❌ URL of the shopping cart
ecommerce.items[].item_id string ✅ Identifier of the product
ecommerce.items[].item_sku string ❌ Stock Keeping Unit (SKU)
ecommerce.items[].item_name string ✅ Name of the product
ecommerce.items[].item_variant string ✅ Variant of the product
ecommerce.items[].item_category string ❌ Category of the product
ecommerce.items[].item_category2 string ❌ Second category hierarchy
ecommerce.items[].item_category3 string ❌ Third category hierarchy
ecommerce.items[].item_category4 string ❌ Fourth category hierarchy
ecommerce.items[].item_category5 string ❌ Fifth category hierarchy
ecommerce.items[].item_brand string ❌ Brand of the product
ecommerce.items[].price float ❌ Price of the product
ecommerce.items[].quantity integer ❌ Quantity of the product in the cart
ecommerce.items[].index integer ❌ Position of the product in the list
ecommerce.items[].coupon string ❌ Coupon applied to the product
ecommerce.items[].discount float ❌ Discount of the item
ecommerce.items[].url string ❌ URL of the product
ecommerce.items[].image_url string ❌ URL of the product image
ecommerce.items[].custom_attribute object ❌ Custom attribute for additional data
ecommerce.items[].item_collection string ❌ Collection of the product
ecommerce.items[].item_collection2 string ❌ Collection of the product
ecommerce.items[].item_collection3 string ❌ Collection of the product
ecommerce.items[].item_list string ❌ List of the product
ecommerce.items[].item_list2 string ❌ List of the product
ecommerce.items[].item_list3 string ❌ List of the product
shipping object ❌ Shipping contact (name, address, phone, etc.)

Example:

_oirtrk.push([
  'event',
  {
    event: 'add_shipping_info',
    ecommerce: {
      order_id: 'ORDER_001',
      value: 59.98,
      shipping: 5.99,
      currency: 'USD',
      shipping_tier: 'Express',
      items: [
        {
          item_id: 'ITM-12345',
          item_name: 'Sample',
          item_variant: 'green',
          price: 29.99,
          quantity: 2,
        },
      ],
    },
    shipping: {
      first_name: 'Alex',
      last_name: 'Morgan',
      address_1: '123 Market St',
      city: 'SF',
      country: 'US',
      postal_code: '94105',
    },
  },
]);
 

Payment Info Added (add_payment_info)

Track when users submit their payment details.

Properties:

Property Type Req Description
event string ✅ Must be add_payment_info
ecommerce object ✅ Event attributes
ecommerce.value float ✅ Order total
ecommerce.shipping float ❌ Shipping cost
ecommerce.currency string ❌ Currency
ecommerce.coupon string ❌ Coupon
ecommerce.payment_type string ✅ Payment method
ecommerce.items array ✅ Items
ecommerce.items[].cart_id string ❌ Unique identifier of the shopping cart
ecommerce.items[].cart_url string ❌ URL of the shopping cart
ecommerce.items[].item_id string ✅ Identifier of the product
ecommerce.items[].item_sku string ❌ Stock Keeping Unit (SKU)
ecommerce.items[].item_name string ✅ Name of the product
ecommerce.items[].item_variant string ✅ Variant of the product
ecommerce.items[].item_category string ❌ Category of the product
ecommerce.items[].item_category2 string ❌ Second category hierarchy
ecommerce.items[].item_category3 string ❌ Third category hierarchy
ecommerce.items[].item_category4 string ❌ Fourth category hierarchy
ecommerce.items[].item_category5 string ❌ Fifth category hierarchy
ecommerce.items[].item_brand string ❌ Brand of the product
ecommerce.items[].price float ❌ Price of the product
ecommerce.items[].quantity integer ❌ Quantity of the product in the cart
ecommerce.items[].index integer ❌ Position of the product in the list
ecommerce.items[].coupon string ❌ Coupon applied to the product
ecommerce.items[].discount float ❌ Discount of the item
ecommerce.items[].url string ❌ URL of the product
ecommerce.items[].image_url string ❌ URL of the product image
ecommerce.items[].custom_attribute object ❌ Custom attribute for additional data
ecommerce.items[].item_collection string ❌ Collection of the product
ecommerce.items[].item_collection2 string ❌ Collection of the product
ecommerce.items[].item_collection3 string ❌ Collection of the product
ecommerce.items[].item_list string ❌ List of the product
ecommerce.items[].item_list2 string ❌ List of the product
ecommerce.items[].item_list3 string ❌ List of the product
billing object ❌ Billing contact (name, email, address, etc.)

Example:

_oirtrk.push([
  'event',
  {
    event: 'add_payment_info',
    ecommerce: {
      value: 59.98,
      shipping: 5.99,
      currency: 'USD',
      payment_type: 'Credit Card',
      items: [
        {
          item_id: 'ITM-12345',
          item_name: 'Sample',
          item_variant: 'green',
          price: 29.99,
          quantity: 2,
        },
      ],
    },
    billing: {
      first_name: 'Alex',
      last_name: 'Morgan',
      email: 'alex@example.com',
    },
  },
]);
 

Purchase & Refund

Order Placed (purchase)

Track when users complete a purchase.

Properties:

Property Type Req Description
event string ✅ Must be purchase
ecommerce object ✅ Event attributes
ecommerce.order_id string ✅ Order identifier
ecommerce.value float ✅ Order value
ecommerce.currency string ❌ Currency
ecommerce.revenue float ❌ Revenue
ecommerce.shipping float ❌ Shipping cost
ecommerce.tax float ❌ Tax amount
ecommerce.discount float ❌ Discount
ecommerce.coupon string ❌ Coupon
ecommerce.items array ✅ Items
ecommerce.items[].cart_id string ❌ Unique identifier of the shopping cart
ecommerce.items[].cart_url string ❌ URL of the shopping cart
ecommerce.items[].item_id string ✅ Identifier of the product
ecommerce.items[].item_sku string ❌ Stock Keeping Unit (SKU)
ecommerce.items[].item_name string ✅ Name of the product
ecommerce.items[].item_variant string ✅ Variant of the product
ecommerce.items[].item_category string ❌ Category of the product
ecommerce.items[].item_category2 string ❌ Second category hierarchy
ecommerce.items[].item_category3 string ❌ Third category hierarchy
ecommerce.items[].item_category4 string ❌ Fourth category hierarchy
ecommerce.items[].item_category5 string ❌ Fifth category hierarchy
ecommerce.items[].item_brand string ❌ Brand of the product
ecommerce.items[].price float ❌ Price of the product
ecommerce.items[].quantity integer ❌ Quantity of the product in the cart
ecommerce.items[].index integer ❌ Position of the product in the list
ecommerce.items[].coupon string ❌ Coupon applied to the product
ecommerce.items[].discount float ❌ Discount of the item
ecommerce.items[].url string ❌ URL of the product
ecommerce.items[].image_url string ❌ URL of the product image
ecommerce.items[].custom_attribute object ❌ Custom attribute for additional data
ecommerce.items[].item_collection string ❌ Collection of the product
ecommerce.items[].item_collection2 string ❌ Collection of the product
ecommerce.items[].item_collection3 string ❌ Collection of the product
ecommerce.items[].item_list string ❌ List of the product
ecommerce.items[].item_list2 string ❌ List of the product
ecommerce.items[].item_list3 string ❌ List of the product
billing object ❌ Billing contact
shipping object ❌ Shipping contact

Example:

_oirtrk.push([
  'event',
  {
    event: 'purchase',
    ecommerce: {
      order_id: 'ORDER_001',
      total_items: 2,
      value: 189.98,
      revenue: 189.98,
      shipping: 12.99,
      tax: 16.2,
      discount: 20.0,
      currency: 'USD',
      coupon: 'SAVE20',
      items: [
        {
          cart_id: 'CART_005',
          cart_url: 'https://example.com/cart/005',
          item_id: 'WATCH_SILVER_42',
          item_name: 'Silver Smart Watch',
          item_variant: 'silver',
          item_category: 'Electronics',
          item_category2: 'Wearables',
          item_category3: 'Smart Watches',
          item_category4: 'Fitness',
          item_category5: 'GPS Enabled',
          item_collection: 'Tech Collection',
          item_collection2: 'Smart Watches',
          item_list: 'Best Sellers',
          item_list2: 'Electronics',
          item_brand: 'TechBrand',
          price: 189.98,
          quantity: 1,
          index: 1,
          coupon: 'SAVE20',
          discount: 20.0,
          url: 'https://example.com/product/watch-silver',
          image_url: 'https://example.com/images/watch-silver.jpg',
          item_list_id: 'recommended_products',
          item_list_name: 'Recommended for you',
          custom_attribute: {
            size: '42mm',
            color: 'Silver',
          },
        },
      ],
    },
    billing: {
      first_name: 'Max',
      last_name: 'Min',
      email: 'example@example.com',
      company: 'COMPANY A',
      address_1: 'EXAMPLE ADDRESS 1',
      address_2: 'EXAMPLE ADDRESS 2',
      city: 'CITY A',
      country: 'ABC DE',
      country_code: 'ABC',
      postal_code: '123456',
      phone: '+01 2345678',
    },
    shipping: {
      first_name: 'Max',
      last_name: 'Min',
      email: 'example@example.com',
      company: 'COMPANY A',
      address_1: 'EXAMPLE ADDRESS 1',
      address_2: 'EXAMPLE ADDRESS 2',
      city: 'CITY A',
      country: 'ABC DE',
      country_code: 'ABC',
      postal_code: '123456',
      phone: '+01 2345678',
    },
  },
]);
 

Refund Issued (refund)

Track when items are refunded after purchase.

Properties:

Property Type Req Description
event string ✅ Must be refund
ecommerce object ✅ Event attributes
ecommerce.order_id string ✅ Order identifier
ecommerce.value float ✅ Total refund value
ecommerce.currency string ❌ Currency
ecommerce.items array ✅ Refunded items
ecommerce.items[].cart_id string ❌ Unique identifier of the shopping cart
ecommerce.items[].cart_url string ❌ URL of the shopping cart
ecommerce.items[].item_id string ✅ Identifier of the product
ecommerce.items[].item_sku string ❌ Stock Keeping Unit (SKU)
ecommerce.items[].item_name string ✅ Name of the product
ecommerce.items[].item_variant string ✅ Variant of the product
ecommerce.items[].item_category string ❌ Category of the product
ecommerce.items[].item_category2 string ❌ Second category hierarchy
ecommerce.items[].item_category3 string ❌ Third category hierarchy
ecommerce.items[].item_category4 string ❌ Fourth category hierarchy
ecommerce.items[].item_category5 string ❌ Fifth category hierarchy
ecommerce.items[].item_brand string ❌ Brand of the product
ecommerce.items[].price float ❌ Price of the product
ecommerce.items[].quantity integer ❌ Quantity of the product in the cart
ecommerce.items[].index integer ❌ Position of the product in the list
ecommerce.items[].coupon string ❌ Coupon applied to the product
ecommerce.items[].discount float ❌ Discount of the item
ecommerce.items[].url string ❌ URL of the product
ecommerce.items[].image_url string ❌ URL of the product image
ecommerce.items[].custom_attribute object ❌ Custom attribute for additional data
ecommerce.items[].item_collection string ❌ Collection of the product
ecommerce.items[].item_collection2 string ❌ Collection of the product
ecommerce.items[].item_collection3 string ❌ Collection of the product
ecommerce.items[].item_list string ❌ List of the product
ecommerce.items[].item_list2 string ❌ List of the product
ecommerce.items[].item_list3 string ❌ List of the product

Example:

_oirtrk.push([
  'event',
  {
    event: 'refund',
    ecommerce: {
      order_id: 'ORDER_001',
      value: 29.99,
      currency: 'USD',
      items: [
        {
          item_id: 'ITM-12345',
          item_sku: 'SKU-12345',
          item_name: 'Sample',
          item_variant: 'green',
          price: 29.99,
          quantity: 1,
        },
      ],
    },
  },
]);
 

Promotion Events

View Promotion (view_promotion)

Track when a promotion is displayed.

Properties:

Property Type Req Description
event string ✅ Must be view_promotion
ecommerce object ✅ Event attributes
ecommerce.promotion_id string ❌ Promotion identifier
ecommerce.promotion_name string ❌ Promotion name
ecommerce.creative_name string ❌ Creative name
ecommerce.creative_slot string ❌ Placement/slot
ecommerce.items array ✅ Associated items
ecommerce.items[].cart_id string ❌ Unique identifier of the shopping cart
ecommerce.items[].cart_url string ❌ URL of the shopping cart
ecommerce.items[].item_id string ✅ Identifier of the product
ecommerce.items[].item_sku string ❌ Stock Keeping Unit (SKU)
ecommerce.items[].item_name string ✅ Name of the product
ecommerce.items[].item_variant string ✅ Variant of the product
ecommerce.items[].item_category string ❌ Category of the product
ecommerce.items[].item_category2 string ❌ Second category hierarchy
ecommerce.items[].item_category3 string ❌ Third category hierarchy
ecommerce.items[].item_category4 string ❌ Fourth category hierarchy
ecommerce.items[].item_category5 string ❌ Fifth category hierarchy
ecommerce.items[].item_brand string ❌ Brand of the product
ecommerce.items[].price float ❌ Price of the product
ecommerce.items[].quantity integer ❌ Quantity of the product in the cart
ecommerce.items[].index integer ❌ Position of the product in the list
ecommerce.items[].coupon string ❌ Coupon applied to the product
ecommerce.items[].discount float ❌ Discount of the item
ecommerce.items[].url string ❌ URL of the product
ecommerce.items[].image_url string ❌ URL of the product image
ecommerce.items[].custom_attribute object ❌ Custom attribute for additional data
ecommerce.items[].item_collection string ❌ Collection of the product
ecommerce.items[].item_collection2 string ❌ Collection of the product
ecommerce.items[].item_collection3 string ❌ Collection of the product
ecommerce.items[].item_list string ❌ List of the product
ecommerce.items[].item_list2 string ❌ List of the product
ecommerce.items[].item_list3 string ❌ List of the product

Example:

_oirtrk.push([
  'event',
  {
    event: 'view_promotion',
    ecommerce: {
      promotion_id: 'P_12345',
      promotion_name: 'Summer Sale',
      creative_name: 'Summer Banner',
      creative_slot: 'homepage_top',
      items: [
        {
          cart_id: 'CART_1',
          cart_url: 'https://example.com/cart/123',
          variant_id: 'green',
          item_id: 'ITM-12345',
          item_sku: 'SKU-12345',
          item_name: 'Sample',
          item_variant: 'green',
          price: 10.01,
          quantity: 3,
          index: 1,
          url: 'https://example.com/product/123',
          image_url: 'https://example.com/product/123/image',
          item_list_id: 'related_products',
          item_list_name: 'Related products',
          item_collection: 'Shirt',
          item_collection2: 'Adult',
          item_collection3: 'Summer',
          item_list: 'Shirt',
          item_list2: 'Adult',
          item_list3: 'Seasonal',
        },
      ],
    },
  },
]);
 

Select Promotion (select_promotion)

Track when a promotion is clicked.

Properties:

Property Type Req Description
event string ✅ Must be select_promotion
ecommerce object ✅ Event attributes
ecommerce.promotion_id string ❌ Promotion identifier
ecommerce.promotion_name string ❌ Promotion name
ecommerce.creative_name string ❌ Creative name
ecommerce.creative_slot string ❌ Placement/slot
ecommerce.items array ✅ Selected items
ecommerce.items[].cart_id string ❌ Unique identifier of the shopping cart
ecommerce.items[].cart_url string ❌ URL of the shopping cart
ecommerce.items[].item_id string ✅ Identifier of the product
ecommerce.items[].item_sku string ❌ Stock Keeping Unit (SKU)
ecommerce.items[].item_name string ✅ Name of the product
ecommerce.items[].item_variant string ✅ Variant of the product
ecommerce.items[].item_category string ❌ Category of the product
ecommerce.items[].item_category2 string ❌ Second category hierarchy
ecommerce.items[].item_category3 string ❌ Third category hierarchy
ecommerce.items[].item_category4 string ❌ Fourth category hierarchy
ecommerce.items[].item_category5 string ❌ Fifth category hierarchy
ecommerce.items[].item_brand string ❌ Brand of the product
ecommerce.items[].price float ❌ Price of the product
ecommerce.items[].quantity integer ❌ Quantity of the product in the cart
ecommerce.items[].index integer ❌ Position of the product in the list
ecommerce.items[].coupon string ❌ Coupon applied to the product
ecommerce.items[].discount float ❌ Discount of the item
ecommerce.items[].url string ❌ URL of the product
ecommerce.items[].image_url string ❌ URL of the product image
ecommerce.items[].custom_attribute object ❌ Custom attribute for additional data
ecommerce.items[].item_collection string ❌ Collection of the product
ecommerce.items[].item_collection2 string ❌ Collection of the product
ecommerce.items[].item_collection3 string ❌ Collection of the product
ecommerce.items[].item_list string ❌ List of the product
ecommerce.items[].item_list2 string ❌ List of the product
ecommerce.items[].item_list3 string ❌ List of the product

Example:

_oirtrk.push([
  'event',
  {
    event: 'select_promotion',
    ecommerce: {
      promotion_id: 'P_12345',
      promotion_name: 'Summer Sale',
      creative_name: 'Summer Banner',
      creative_slot: 'homepage_top',
      items: [
        {
          cart_id: 'CART_1',
          cart_url: 'https://example.com/cart/123',
          variant_id: 'green',
          item_id: 'ITM-12345',
          item_sku: 'SKU-12345',
          item_name: 'Sample',
          item_variant: 'green',
          price: 10.01,
          quantity: 1,
          index: 1,
          url: 'https://example.com/product/123',
          image_url: 'https://example.com/product/123/image',
          item_list_id: 'related_products',
          item_list_name: 'Related products',
          item_collection: 'Shirt',
          item_collection2: 'Adult',
          item_collection3: 'Summer',
          item_list: 'Shirt',
          item_list2: 'Adult',
          item_list3: 'Seasonal',
        },
      ],
    },
  },
]);
 

Validation

Ecommerce Event Validation

function validateEcommerceData(data) {
  const required = ['item_id', 'item_name', 'item_variant'];

  if (!data.ecommerce) {
    throw new Error('Missing ecommerce object');
  }

  if (!data.ecommerce.items || !Array.isArray(data.ecommerce.items)) {
    throw new Error('ecommerce.items must be an array');
  }

  if (data.ecommerce.items.length === 0) {
    throw new Error('ecommerce.items cannot be empty');
  }

  data.ecommerce.items.forEach((item, index) => {
    required.forEach(field => {
      if (!item[field]) {
        throw new Error(`Item at index ${index} is missing required field: ${field}`);
      }
    });

    // Validate data types
    if (item.price !== undefined && typeof item.price !== 'number') {
      throw new Error(`Item at index ${index}: price must be a number`);
    }

    if (item.quantity !== undefined && typeof item.quantity !== 'number') {
      throw new Error(`Item at index ${index}: quantity must be a number`);
    }

    if (item.discount !== undefined && typeof item.discount !== 'number') {
      throw new Error(`Item at index ${index}: discount must be a number`);
    }
  });

  // Validate currency (if present)
  if (data.ecommerce.currency && typeof data.ecommerce.currency !== 'string') {
    throw new Error('currency must be a string');
  }

  // Validate value (if present)
  if (data.ecommerce.value !== undefined && typeof data.ecommerce.value !== 'number') {
    throw new Error('value must be a number');
  }

  return true;
}
 

Usage Example

function trackEcommerceEvent(eventData) {
  try {
    // Validate data before sending
    validateEcommerceData(eventData);

    // Send event
    window._oirtrk.push(['event', eventData]);
    console.log('E-commerce event tracked successfully');
  } catch (error) {
    console.error('Ecommerce tracking error:', error.message);
  }
}

// Example usage
const addToCartData = {
  event: 'add_to_cart',
  ecommerce: {
    currency: 'USD',
    value: 29.99,
    items: [
      {
        item_id: 'ITM-12345',
        item_name: 'Blue T-Shirt',
        item_variant: 'blue',
        item_category: 'Apparel',
        price: 29.99,
        quantity: 1,
      },
    ],
  },
};

trackEcommerceEvent(addToCartData);
 

Best Practices

1. Always Include Required Fields

// ❌ BAD - Missing required fields
{
  event: 'add_to_cart',
  ecommerce: {
    items: [
      {
        item_id: 'ITM-12345',
        // Missing item_name and item_variant
      }
    ]
  }
}

// ✅ GOOD - All required fields present
{
  event: 'add_to_cart',
  ecommerce: {
    currency: 'USD',
    value: 29.99,
    items: [
      {
        item_id: 'ITM-12345',
        item_name: 'Blue T-Shirt',
        item_variant: 'blue',
        price: 29.99,
        quantity: 1
      }
    ]
  }
}
 

2. Use Correct Data Types

// ❌ BAD - Wrong data types
{
  item_id: 'ITM-12345',
  item_name: 'Product',
  item_variant: 'blue',
  price: '29.99',      // Should be number
  quantity: '1'        // Should be number
}

// ✅ GOOD - Correct data types
{
  item_id: 'ITM-12345',
  item_name: 'Product',
  item_variant: 'blue',
  price: 29.99,        // Number
  quantity: 1          // Number
}
 

3. Minimize Payload Size

// ❌ BAD - Unnecessary data
{
  item_id: 'ITM-12345',
  item_name: 'Product',
  item_variant: 'blue',
  unnecessary_field_1: null,
  unnecessary_field_2: undefined,
  unused_metadata: {}
}

// ✅ GOOD - Clean payload
{
  item_id: 'ITM-12345',
  item_name: 'Product',
  item_variant: 'blue',
  price: 29.99,
  quantity: 1
}
 

4. Use Consistent Property Names

// Use the same property names everywhere
const standardItem = {
  item_id: product.sku, // Always use item_id
  item_name: product.title, // Always use item_name
  item_variant: product.color, // Always use item_variant
  price: product.price,
  quantity: product.qty,
};
 

5. Privacy Compliance

  • Don't include PII in event data—use the identify function instead
  • Follow GDPR, CCPA regulations
  • Only track necessary data

 

Debug Checklist

Use this checklist when troubleshooting ecommerce tracking:

  •  SDK loaded correctly (window._oirtrk is defined)
  •  Configuration set properly (oirid and oirtyp configured)
  •  All required fields included (item_id, item_name, item_variant)
  •  Data types are correct (numbers for price, quantity, value)
  •  Currency code is valid (ISO 4217 format, e.g., 'USD', 'EUR')
  •  No console errors in browser DevTools
  •  Network requests visible in Network tab
  •  Event data structure matches documentation

Next Steps