Ecommerce Events

Updated

How it works

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

Our ecommerce specification helps you send events in a uniform format that maps destination 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., making it easier to set up destinations. When you send data using our ecommerce specification, you can use our out-of-the-box actions without having to map your incoming data to each destination.

Handling arrays of products

Some destinations don’t take arrays. In these cases, you may need to flatten arrays of products. See individual destination documentation for more information on supported events and properties.

Event lifecycles

You can see a complete list of ecommerce events and all associated properties on our 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 client-side library. But you can send ecommerce events from any source.

Browsing products

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

ActionDescription
Products SearchedUser searched for products
Product List ViewedUser viewed a product list or category
Product List FilteredUser filtered a product list or category
analytics.track('Products Searched', {
  query: "pepperoni pizza"
})
  • query string
    The search query the customer entered.

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.

ActionDescription
Promotion ViewedUser viewed promotion
Promotion ClickedUser clicked on promotion
analytics.track('Promotion Viewed', {
  promotion_id: "promo-123",
  creative: "top_banner_2",
  name: "75% store-wide shoe sale",
  position: "banner_slot_1"
})
  • creative string
    The creative content ID associated with the promotion.
  • name string
    The name of the promotion a person viewed.
  • position string
    The position of the promotion a person viewed.
  • promotion_id string
    The ID of the promotion a person viewed.

Product order overview

These events represent the typical lifecycle of a product order.

ActionDescription
Product ClickedUser clicked on a product
Product ViewedUser viewed a product details
Product AddedUser added a product to their shopping cart
Product RemovedUser removed a product from their shopping cart
Cart ViewedUser viewed their shopping cart
Checkout StartedUser 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 ViewedUser viewed a checkout step. You can have as many checkout steps as you want.
Checkout Step CompletedUser completed a checkout step. You can have as many checkout steps as you want.
Payment Info EnteredUser added payment information
Order CompletedUser completed the order
Order UpdatedUser updated the order
Order RefundedUser refunded the order
Order CancelledUser cancelled the order
analytics.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
})
  • brand string
    The brand associated with the product.
  • category string
    The product category a person viewed.
  • coupon string
    The coupon code associated with the product (like NEWUSER20).
  • image_url string
    The URL of the product image.
  • name string
    The name of the product a person viewed.
  • position number
    The position of the product in the list.
  • price number
    The price of the product.
  • product_id string
    The product ID.
  • quantity integer
    The quantity of the product.
  • 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.
  • currency string
    The currency of the transaction.
  • value number
    The total value of the product, after multiplying by quantity.

Coupons overview

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

ActionDescription
Coupon EnteredUser entered a coupon on a shopping cart or order
Coupon AppliedCoupon was applied on a user’s shopping cart or order
Coupon DeniedCoupon was denied from a user’s shopping cart or order
Coupon RemovedUser removed a coupon from a cart or order
analytics.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.

ActionDescription
Product Added to WishlistUser added a product to the wish list
Product Removed from WishlistUser removed a product from the wish list
Wishlist Product Added to CartUser added a wishlist product to the cart
analytics.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"
})
  • wishlist_id string
    The ID of the wishlist that the product applies to.
  • wishlist_name string
    The name of the wishlist that the product applies to.
  • brand string
    The brand associated with the product.
  • category string
    The product category a person viewed.
  • coupon string
    The coupon code associated with the product (like NEWUSER20).
  • image_url string
    The URL of the product image.
  • name string
    The name of the product a person viewed.
  • position number
    The position of the product in the list.
  • price number
    The price of the product.
  • product_id string
    The product ID.
  • quantity integer
    The quantity of the product.
  • 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.

Sharing overview

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

ActionDescription
Product SharedShared a product with one or more friends
Cart SharedShared the cart with one or more friends
analytics.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.
  • product_id string
    The product ID.
  • 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.

Reviewing overview

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

ActionDescription
Product ReviewedUser reviewed a product
analytics.track('Product Reviewed', {
  product_id: "coolshoes-123",
  review_id: "review_123",
  review_body: "These shoes are great!",
  rating: 5
})
  • product_id string
    The product ID.
  • 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!
  Contents
Is this page helpful?