Ecommerce Events

Updated February 19, 2026

How it works

Ecommerce track events typically contain the same information across platforms—products, brands, orders, cart information, etc. However, each place you send this data to might map this information differently.

Our ecommerce specification helps you send events in a uniform format that maps to the actionsThe source event and data that triggers an API call to your destination. For example, an incoming identify event from your sources adds or updates a person in our Customer.io Journeys destination. for any of our ecommerce-supporting integrations. This means can use our out-of-the-box actions without having to map your incoming data to each outbound integration.

Handling arrays of products

Some data-out integrations don’t take arrays. In these cases, you may need to flatten arrays of products. See the documentation for your integration to learn more information about supported events and properties.

Event lifecycles

You can see a complete list of ecommerce events and all associated properties on our Pipelines API reference page. But it can also help to understand the typical events that a person may perform and the order they’re likely to perform them in, as they browse and buy products.

Examples in this section are based on our JavaScript library

To simplify the examples on this page, we’ve based everything on our JavaScript client. But you can send ecommerce events from any of our libraries.

Browsing products

Browsing events represent key events that a customer might have while browsing for products.

Action	Description
Products Searched	User searched for products
Product List Viewed	User viewed a product list or category
Product List Filtered	User filtered a product list or category

cioanalytics.track('Products Searched', {
  query: "pepperoni pizza"
})

query string
The search query the customer entered.

cioanalytics.track('Product List Viewed', {
  list_id: 'hot_deals_1',
  category: 'Deals',
  products: [
    {
      product_id: "coolshoes-123"
      sku: "abc-123-xyz"
      category: "shoes"
      name: "Cool Shoes"
      brand: "A Shoe Brand"
      price: 139.99
      position: 1
      url: "https://www.example.com/product/123"
      image_url: "https://www.example.com/product/123.jpg"
    },
    {
      product_id: "coolshoes-456"
      sku: "abc-456-xyz"
      category: "shoes"
      name: "Even Cooler Shoes"
      brand: "A Different Shoe Brand"
      price: 159.99
      position: 2
      url: "https://www.example.com/product/456"
      image_url: "https://www.example.com/product/456.jpg"
    }
  ]
});

cioanalytics.track('Product List Filtered', {
  list_id: "all_shoes",
  category: "shoes",
  products: [
    {
      product_id: "coolshoes-123",
      sku: "abc-123-xyz",
      category: "shoes",
      name: "Cool Shoes",
      brand: "A Shoe Brand",
      variant: "red",
      price: 139.99,
      quantity: 1,
      coupon: "NEWUSER20",
      position: 3,
      url: "https://www.example.com/product/123",
      image_url: "https://www.example.com/product/123.jpg"
    }
  ],
  filters: [
    {
      type: "string",
      value: "string"
    }
  ],
  sorts: [
    {
      type: "string",
      value: "string"
    }
  ]
})

Promotions overview

Promotion events let you know when someone sees or interacts with offers within your app. For example, you might send a Promotion Viewed event when your app shows a banner advertisement to a user. If the user clicks the ad, you’d send the Promotion Clicked event.

Action	Description
Promotion Viewed	User viewed promotion
Promotion Clicked	User clicked on promotion

cioanalytics.track('Promotion Viewed', {
  promotion_id: "promo-123",
  creative: "top_banner_2",
  name: "75% store-wide shoe sale",
  position: "banner_slot_1"
})

Product order overview

These events represent the typical lifecycle of a product order.

Action	Description
Product Clicked	User clicked on a product
Product Viewed	User viewed a product details
Product Added	User added a product to their shopping cart
Product Removed	User removed a product from their shopping cart
Cart Viewed	User viewed their shopping cart
Checkout Started	User initiated the order process (a transaction is created) You should send this event on the page that the customer lands on after they click Checkout (or a similar button).
Checkout Step Viewed	User viewed a checkout step. You can have as many checkout steps as you want.
Checkout Step Completed	User completed a checkout step. You can have as many checkout steps as you want.
Payment Info Entered	User added payment information
Order Completed	User completed the order
Order Updated	User updated the order
Order Refunded	User refunded the order
Order Cancelled	User cancelled the order

cioanalytics.track('Product Clicked', {
  product_id: "coolshoes-123"
  sku: "abc-123-xyz"
  category: "shoes"
  name: "Cool Shoes"
  brand: "A Shoe Brand"
  variant: "red"
  price: 139.99
  quantity: 1
  coupon: "NEWUSER20"
  position: 3
  url: "https://www.example.com/product/123"
  image_url: "https://www.example.com/product/123.jpg"
  currency: "USD"
  value: 119.99
})

cioanalytics.track('Product Viewed', {
  product_id: "coolshoes-123"
  sku: "abc-123-xyz"
  category: "shoes"
  name: "Cool Shoes"
  brand: "A Shoe Brand"
  variant: "red"
  price: 139.99
  quantity: 1
  coupon: "NEWUSER20"
  position: 3
  url: "https://www.example.com/product/123"
  image_url: "https://www.example.com/product/123.jpg"
  currency: "USD"
  value: 119.99
})

cioanalytics.track('Product Added', {
  product_id: "coolshoes-123"
  sku: "abc-123-xyz"
  category: "shoes"
  name: "Cool Shoes"
  brand: "A Shoe Brand"
  variant: "red"
  price: 139.99
  quantity: 1
  coupon: "NEWUSER20"
  position: 3
  url: "https://www.example.com/product/123"
  image_url: "https://www.example.com/product/123.jpg"
  currency: "USD"
  value: 119.99
})

cioanalytics.track('Product Removed', {
  product_id: "coolshoes-123"
  sku: "abc-123-xyz"
  category: "shoes"
  name: "Cool Shoes"
  brand: "A Shoe Brand"
  variant: "red"
  price: 139.99
  quantity: 1
  coupon: "NEWUSER20"
  position: 3
  url: "https://www.example.com/product/123"
  image_url: "https://www.example.com/product/123.jpg"
  currency: "USD"
  value: 119.99
})

cioanalytics.track('Cart Viewed', {
  cart_id: "cool_persons_cart_123",
  products: [
    {
      product_id: "coolshoes-123",
      sku: "abc-123-xyz",
      category: "shoes",
      name: "Cool Shoes",
      brand: "A Shoe Brand",
      variant: "red",
      price: 139.99,
      quantity: 1,
      coupon: "NEWUSER20",
      position: 3,
      url: "https://www.example.com/product/123",
      image_url: "https://www.example.com/product/123.jpg"
    }
  ]
})

cart_id string
The cart ID a person viewed.
products array of [ objects ]
The products in the cart. Each object in the array represents a product.

cioanalytics.track('Checkout Started', {
  order_id: "cool_persons_cart_123",
  affiliation: "Shopify",
  revenue: 139.99,
  shipping: 5,
  tax: 10,
  discount: 20,
  coupon: "NEWUSER20",
  currency: "USD",
  products: [
    {
      product_id: "coolshoes-123",
      sku: "abc-123-xyz",
      category: "shoes",
      name: "Cool Shoes",
      brand: "A Shoe Brand",
      variant: "red",
      price: 139.99,
      quantity: 1,
      coupon: "NEWUSER20",
      position: 3,
      url: "https://www.example.com/product/123",
      image_url: "https://www.example.com/product/123.jpg"
    }
  ]
})

cioanalytics.track('Checkout Step Viewed', {
  checkout_id: "cool_persons_checkout_123",
  step: 2,
  shipping_method: "ground",
  payment_method: "Visa"
})

checkout_id string
The checkout/transaction ID.
payment_method string
The payment method selected by the user.
shipping_method string
The shipping method selected by the user.
step integer
The step number of the checkout process.

cioanalytics.track('Checkout Step Completed', {
  checkout_id: "cool_persons_checkout_123",
  step: 2,
  shipping_method: "ground",
  payment_method: "Visa"
})

checkout_id string
The checkout/transaction ID.
payment_method string
The payment method selected by the user.
shipping_method string
The shipping method selected by the user.
step integer
The step number of the checkout process.

cioanalytics.track('Payment Info Entered', {
  checkout_id: "cool_persons_checkout_123",
  step: 2,
  shipping_method: "ground",
  payment_method: "Visa",
  order_id: "order123"
})

cioanalytics.track('Order Completed', {
  subtotal: 119.99,
  products: [
    {
      product_id: "coolshoes-123",
      sku: "abc-123-xyz",
      category: "shoes",
      name: "Cool Shoes",
      brand: "A Shoe Brand",
      variant: "red",
      price: 139.99,
      quantity: 1,
      coupon: "NEWUSER20",
      position: 3,
      url: "https://www.example.com/product/123",
      image_url: "https://www.example.com/product/123.jpg"
    }
  ],
  order_id: "cool_persons_cart_123",
  checkout_id: "checkout123",
  total: 0,
  affiliation: "Shopify",
  revenue: 139.99,
  shipping: 5,
  tax: 10,
  discount: 20,
  coupon: "NEWUSER20",
  currency: "USD"
})

cioanalytics.track('Order Updated', {
  order_id: "cool_persons_cart_123",
  affiliation: "Shopify",
  revenue: 139.99,
  shipping: 5,
  tax: 10,
  discount: 20,
  coupon: "NEWUSER20",
  currency: "USD",
  products: [
    {
      product_id: "coolshoes-123",
      sku: "abc-123-xyz",
      category: "shoes",
      name: "Cool Shoes",
      brand: "A Shoe Brand",
      variant: "red",
      price: 139.99,
      quantity: 1,
      coupon: "NEWUSER20",
      position: 3,
      url: "https://www.example.com/product/123",
      image_url: "https://www.example.com/product/123.jpg"
    }
  ]
})

cioanalytics.track('Order Refunded', {
  order_id: "order123",
  affiliation: "Shopify",
  revenue: 139.99,
  shipping: 5,
  tax: 10,
  discount: 20,
  coupon: "NEWUSER20",
  currency: "USD",
  products: [
    {
      product_id: "coolshoes-123",
      sku: "abc-123-xyz",
      category: "shoes",
      name: "Cool Shoes",
      brand: "A Shoe Brand",
      variant: "red",
      price: 139.99,
      quantity: 1,
      coupon: "NEWUSER20",
      position: 3,
      url: "https://www.example.com/product/123",
      image_url: "https://www.example.com/product/123.jpg"
    }
  ],
  total: 119.99,
  subtotal: 119.99,
  checkout_id: "checkout123"
})

cioanalytics.track('Order Cancelled', {
  order_id: "order123",
  affiliation: "Shopify",
  revenue: 139.99,
  shipping: 5,
  tax: 10,
  discount: 20,
  coupon: "NEWUSER20",
  currency: "USD",
  products: [
    {
      product_id: "coolshoes-123",
      sku: "abc-123-xyz",
      category: "shoes",
      name: "Cool Shoes",
      brand: "A Shoe Brand",
      variant: "red",
      price: 139.99,
      quantity: 1,
      coupon: "NEWUSER20",
      position: 3,
      url: "https://www.example.com/product/123",
      image_url: "https://www.example.com/product/123.jpg"
    }
  ],
  total: 119.99
})

Coupons overview

Send coupon events when your customers enter, apply, or remove coupons from their shopping carts or orders.

Action	Description
Coupon Entered	User entered a coupon on a shopping cart or order
Coupon Applied	Coupon was applied on a user’s shopping cart or order
Coupon Denied	Coupon was denied from a user’s shopping cart or order
Coupon Removed	User removed a coupon from a cart or order

cioanalytics.track('Coupon Entered', {
  order_id: "order123",
  cart_id: "cool_persons_cart_123",
  coupon_id: "NEWUSER20"
})

cart_id string
The ID of the cart that the coupon applies to (if applicable).
coupon_id string
the coupon ID the person entered.
order_id string
The order/transaction the coupon applies to (if applicable).

Wishlisting overview

Send these events if your ecommerce app supports wishlist features.

Action	Description
Product Added to Wishlist	User added a product to the wish list
Product Removed from Wishlist	User removed a product from the wish list
Wishlist Product Added to Cart	User added a wishlist product to the cart

cioanalytics.track('Product Added to Wishlist', {
  wishlist_id: "wishlist123",
  wishlist_name: "Favorite Shoes",
  product_id: "coolshoes-123",
  sku: "abc-123-xyz",
  category: "shoes",
  name: "Cool Shoes",
  brand: "A Shoe Brand",
  variant: "red",
  price: 139.99,
  quantity: 1,
  coupon: "NEWUSER20",
  position: 3,
  url: "https://www.example.com/product/123",
  image_url: "https://www.example.com/product/123.jpg"
})

cioanalytics.track('Product Removed from Wishlist', {
  wishlist_id: "wishlist123",
  wishlist_name: "Favorite Shoes",
  product_id: "coolshoes-123",
  sku: "abc-123-xyz",
  category: "shoes",
  name: "Cool Shoes",
  brand: "A Shoe Brand",
  variant: "red",
  price: 139.99,
  quantity: 1,
  coupon: "NEWUSER20",
  position: 3,
  url: "https://www.example.com/product/123",
  image_url: "https://www.example.com/product/123.jpg"
})

cioanalytics.track('Wishlist Product Added to Cart', {
  wishlist_id: "wishlist123",
  wishlist_name: "Favorite Shoes",
  product_id: "coolshoes-123",
  sku: "abc-123-xyz",
  category: "shoes",
  name: "Cool Shoes",
  brand: "A Shoe Brand",
  variant: "red",
  price: 139.99,
  quantity: 1,
  coupon: "NEWUSER20",
  position: 3,
  url: "https://www.example.com/product/123",
  image_url: "https://www.example.com/product/123.jpg"
})

If your store integrates with social apps or or supports sharing, you can send events when your customers share product information.

Action	Description
Product Shared	Shared a product with one or more friends
Cart Shared	Shared the cart with one or more friends

cioanalytics.track('Product Shared', {
  share_via: "email",
  share_message: "Check out these cool shoes!",
  recipient: "friendOfcool.person@example.com",
  product_id: "coolshoes-123",
  sku: "abc-123-xyz",
  category: "shoes",
  name: "Cool Shoes",
  brand: "A Shoe Brand",
  variant: "red",
  price: 139.99,
  url: "https://www.example.com/product/123",
  image_url: "https://www.example.com/product/123.jpg"
})

brand string
The brand associated with the product.
category string
The product category a person viewed.
image_url string
The URL of the product image.
name string
The name of the product a person viewed.
price number
The price of the product.
recipient string
The person the product was shared with.
share_message string
The message the customer sent with the share.
share_via string
The channel the product was shared through.
sku string
The stock keeping unit (SKU) of the product a person viewed.
url string
The URL of the product page.
variant string
The variant of the product a person viewed, if applicable.

cioanalytics.track('Cart Shared', {
  share_via: "email",
  share_message: "Check out my cart!",
  recipient: "friendOfcool.person@example.com",
  cart_id: "cool_persons_cart_123",
  products: [
    {
      product_id: "coolshoes-123"
    }
  ]
})

cart_id string
The shopping cart ID.
products array of [ objects ]
An array of product IDs contained in the shared cart.
recipient string
The person the product was shared with.
share_message string
The message the customer sent with the share.
share_via string
The channel the product was shared through.

Reviewing overview

Send the Product Reviewed event when customers review products in your store.

Action	Description
Product Reviewed	User reviewed a product

cioanalytics.track('Product Reviewed', {
  product_id: "coolshoes-123",
  review_id: "review_123",
  review_body: "These shoes are great!",
  rating: 5
})

rating integer
The rating the customer gave the product.
review_body string
The body of the review.
review_id string
The ID of the review.

Copied to clipboard!

Latest features at Customer.io

Notification inbox: messages your audience can revisit

Native WhatsApp support

Set global styles for in-app messages

Ecommerce Events

How it works

Handling arrays of products

Event lifecycles

Browsing products

Products Searched

Product List Viewed

Product List Filtered

Promotions overview

Promotion Viewed

Promotion Clicked

Product order overview

Product Clicked

Product Viewed

Product Added

Product Removed

Cart Viewed

Checkout Started

Checkout Step Viewed

Checkout Step Completed

Payment Info Entered

Order Completed

Order Updated

Order Refunded

Order Cancelled

Coupons overview

Coupon Entered

Coupon Applied

Coupon Denied

Coupon Removed

Wishlisting overview

Product Added to Wishlist

Product Removed from Wishlist

Wishlist Product Added to Cart

Reviewing overview

Latest features at Customer.io

Notification inbox: messages your audience can revisit

Native WhatsApp support

Set global styles for in-app messages

Ecommerce Events

How it works

Handling arrays of products

Event lifecycles

Browsing products

Products Searched

Product List Viewed

Product List Filtered

Promotions overview

Promotion Viewed

Promotion Clicked

Product order overview

Product Clicked

Product Viewed

Product Added

Product Removed

Cart Viewed

Checkout Started

Checkout Step Viewed

Checkout Step Completed

Payment Info Entered

Order Completed

Order Updated

Order Refunded

Order Cancelled

Coupons overview

Coupon Entered

Coupon Applied

Coupon Denied

Coupon Removed

Wishlisting overview

Product Added to Wishlist

Product Removed from Wishlist

Wishlist Product Added to Cart

Sharing overview

Product Shared

Cart Shared

Reviewing overview

How can we make it better?