# Ecommerce Events

## How it works[](#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](/integrations/api/cdp/ecommerce/) 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[](#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[](#event-lifecycles)

You can see a complete list of ecommerce events and all associated properties on our [Pipelines API reference page](/integrations/api/cdp/#section/Semantic-events-for-data-out-integrations/Ecommerce-event-schemas). 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-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

#### Products Searched[](#Products Searched)

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

*   query string
    
    The search query the customer entered.
    

#### Product List Viewed[](#Product List Viewed)

```javascript
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"
    }
  ]
});
```

#### Product List Filtered[](#Product List Filtered)

```javascript
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[](#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

#### Promotion Viewed[](#Promotion Viewed)

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

#### Promotion Clicked[](#Promotion Clicked)

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

### Product order overview[](#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

#### Product Clicked[](#Product Clicked)

```javascript
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
})
```

#### Product Viewed[](#Product Viewed)

```javascript
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
})
```

#### Product Added[](#Product Added)

```javascript
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
})
```

#### Product Removed[](#Product Removed)

```javascript
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
})
```

#### Cart Viewed[](#Cart Viewed)

```javascript
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.
    

#### Checkout Started[](#Checkout Started)

```javascript
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"
    }
  ]
})
```

#### Checkout Step Viewed[](#Checkout Step Viewed)

```javascript
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.
    

#### Checkout Step Completed[](#Checkout Step Completed)

```javascript
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.
    

#### Payment Info Entered[](#Payment Info Entered)

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

#### Order Completed[](#Order Completed)

```javascript
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"
})
```

#### Order Updated[](#Order Updated)

```javascript
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"
    }
  ]
})
```

#### Order Refunded[](#Order Refunded)

```javascript
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"
})
```

#### Order Cancelled[](#Order Cancelled)

```javascript
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[](#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

#### Coupon Entered[](#Coupon Entered)

```javascript
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).
    

#### Coupon Applied[](#Coupon Applied)

cioanalytics.track(‘Coupon Applied’, { order\_id: “order123”, cart\_id: “cool\_persons\_cart\_123”, coupon\_id: “NEWUSER20”, coupon\_name: “$20 off for new users”, discount: 20 })

*   cart\_id string
    
    The ID of the cart that the coupon applies to (if applicable).
    
*   coupon\_id string
    
    the coupon ID the person entered.
    
*   coupon\_name string
    
    The name of the coupon, if applicable.
    
*   discount number
    
    The discount applied through the coupon. This is the ammount subtracted from the `total` in other transaction events.
    
*   order\_id string
    
    The order/transaction the coupon applies to (if applicable).
    

#### Coupon Denied[](#Coupon Denied)

cioanalytics.track(‘Coupon Applied’, { order\_id: “order123”, cart\_id: “cool\_persons\_cart\_123”, coupon\_id: “NEWUSER20”, coupon\_name: “$20 off for new users”, reason: “Not customer’s first order” })

*   cart\_id string
    
    The ID of the cart that the coupon applies to (if applicable).
    
*   coupon\_id string
    
    the coupon ID the person entered.
    
*   coupon\_name string
    
    The name of the coupon, if applicable.
    
*   order\_id string
    
    The order/transaction the coupon applies to (if applicable).
    
*   reason string
    
    The reason the coupon was denied.
    

#### Coupon Removed[](#Coupon Removed)

cioanalytics.track(‘Coupon Removed’, { order\_id: “order123”, cart\_id: “cool\_persons\_cart\_123”, coupon\_id: “NEWUSER20”, coupon\_name: “$20 off for new users”, discount: 20 })

*   cart\_id string
    
    The ID of the cart that the coupon applies to (if applicable).
    
*   coupon\_id string
    
    the coupon ID the person entered.
    
*   coupon\_name string
    
    The name of the coupon, if applicable.
    
*   discount number
    
    The discount applied through the coupon. This is the ammount subtracted from the `total` in other transaction events.
    
*   order\_id string
    
    The order/transaction the coupon applies to (if applicable).
    

### Wishlisting overview[](#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

#### Product Added to Wishlist[](#Product Added to Wishlist)

```javascript
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"
})
```

#### Product Removed from Wishlist[](#Product Removed from Wishlist)

```javascript
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"
})
```

#### Wishlist Product Added to Cart[](#Wishlist Product Added to Cart)

```javascript
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"
})
```

### Sharing overview[](#sharing-overview)

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

#### Product Shared[](#Product Shared)

```javascript
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.
    

#### Cart Shared[](#Cart Shared)

```javascript
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[](#reviewing-overview)

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

**Action**

**Description**

Product Reviewed

User reviewed a product

```javascript
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.