Enhanced ecommerce with gtag.js

This guide describes how to use gtag.js to collect enhanced ecommerce data.

Enhanced ecommerce enables the measurement of user interactions with products on ecommerce websites across the user's shopping experience, including product selections, product detail views, adding a product to a shopping cart, initiating the checkout process, purchases, and refunds.

Enhanced ecommerce events and parameters

If you have configured Google Analytics in gtag.js and you have enhanced ecommerce enabled in Google Analytics, you can use gtag.js to send impression data, product data, promotion data, and action data to Google Analytics.

Impression data

The following item parameters represent information about a product that has been viewed:

Item parameter Data type Required Description
id string Yes* Unique ID/SKU for the item.
name string Yes* Item name.
list_name string No The list in which the item was presented to the user
brand string No Brand of the item
category string No Item category
variant string No Item variant
list_position integer No The position of the item in the list
price currency No Purchase price of the item

*Either id or name must be set.

Product data

The following item parameters represent information about a product that was viewed, added to a shopping cart, etc:

Item parameter Data type Required Description
id string Yes* Unique ID/SKU for the item.
name string Yes* Item name.
brand string No Brand of the item
category string No Item category
variant string No Item variant
price currency No Purchase price of the item
quantity integer No Item quantity
coupon string No Coupon code for a purchasable item
list_position integer No The position of the item in the list

*Either id or name must be set.

Promotion data

The following promotion parameters represent information about a promotion that has been viewed:

Promotion parameter Data type Required Description
id string Yes* Promotion ID.
name string Yes* Name of promotion.
creative_name string No The name of a creative used
creative_slot string No The name of the creative slot

*Either id or name must be set.

Action data

The following event parameters and item parameter represent information about an ecommerce related action that has taken place:

Event parameter Data type Required Description
transaction_id string Yes* Unique ID for the transaction.
affiliation string No The store or affiliation from which this transaction occurred
value number No Value (i.e., revenue) associated with the event
tax currency No Tax amount
shipping currency No Shipping cost
items array No The array containing the associated products
checkout_step number No The step (a number) in the checkout process
checkout_option string No Checkout option (i.e. selected payment method)

*Required for purchase or refund.

Item parameter Data type Required Description
coupon string No Coupon code for a purchasable item

Product and promotion actions

The following actions (events) specify how to interpret product and promotion data that you send to Google Analytics:

Event Description
select_content A click on a product or product link for one or more products.
view_item A view of product details.
add_to_cart Adding one or more products to a shopping cart.
remove_from_cart Removing one or more products from a shopping cart.
begin_checkout Initiating the checkout process for one or more products.
set_checkout_option Sending the option value for a given checkout step.
purchase The sale of one or more products.
refund The refund of one or more products.
view_promotion A click on an internal promotion.

Implementation

The following sections will show you how to use gtag.js to measure the following enhanced ecommerce activities:

Measure product impressions

To measure product impressions, send a view_item_list event and provide the information of the products:

gtag('event', 'view_item_list', {
  "items": [
    {
      "id": "P12345",
      "name": "Android Warhol T-Shirt",
      "list": "Search Results",
      "brand": "Google",
      "category": "Apparel/T-Shirts",
      "variant": "Black",
      "list_position": 1,
      "quantity": 2,
      "price": 2
    },
    {
      "id": "P67890",
      "name": "Flame challenge TShirt",
      "list": "Search Results",
      "brand": "MyBrand",
      "category": "Apparel/T-Shirts",
      "variant": "Red",
      "list_position": 2,
      "quantity": 1,
      "price": 3
    }
  ]
});

Measure product clicks

To measure a product click, send a select_content event, specify product as the content_type, and provide the product information:

gtag('event', 'select_content', {
  "content_type": "product",
  "items": [
    {
      "id": "P12345",
      "name": "Android Warhol T-Shirt",
      "list": "Search Results",
      "brand": "Google",
      "category": "Apparel/T-Shirts",
      "variant": "Black",
      "list_position": 1,
      "quantity": 2,
      "price": 2
    }
  ]
});

Measure a product details view

After clicking a product listing, a user might view the product details page. To measure this product details view, send a view_item event with the product details:

gtag('event', 'view_item', {
  "items": [
    {
      "id": "P12345",
      "name": "Android Warhol T-Shirt",
      "list_name": "Search Results",
      "brand": "Google",
      "category": "Apparel/T-Shirts",
      "variant": "Black",
      "list_position": 1,
      "quantity": 2,
      "price": '2.0'
    }
  ]
});

Measure additions to and removals from shopping cart

To measure the addition of a product to a shopping cart, send an add_to_cart event with the product information:

gtag('event', 'add_to_cart', {
  "items": [
    {
      "id": "P12345",
      "name": "Android Warhol T-Shirt",
      "list_name": "Search Results",
      "brand": "Google",
      "category": "Apparel/T-Shirts",
      "variant": "Black",
      "list_position": 1,
      "quantity": 2,
      "price": '2.0'
    }
  ]
});

To measure the removal of a product from a shopping cart, send an remove_from_cart event with the product information:

gtag('event', 'remove_from_cart', {
  "items": [
    {
      "id": "P12345",
      "name": "Android Warhol T-Shirt",
      "list_name": "Search Results",
      "brand": "Google",
      "category": "Apparel/T-Shirts",
      "variant": "Black",
      "list_position": 1,
      "quantity": 2,
      "price": '2.0'
    }
  ]
});

Measure promotion impressions

To measure promotion impressions, send a view_promotion event and provide the promotions:

gtag('event', 'view_promotion', {
  "promotions": [
    {
      "id": "abc123",
      "name": "summer_promo"
    },
    {
      "id": "xyz987",
      "name": "spring savings"
    }
  ]
});

Measure promotion clicks

To measure a promotion click, send a select_content event and provide the promotion:

gtag('event', 'select_content', {
  "promotions": [
    {
      "id": "abc123",
      "name": "summer_promo"
    }
  ]
});

Measure checkout

To measure each step in a checkout process:

  1. Add tracking code to measure each step of the checkout process.
  2. If applicable, add tracking code to measure checkout options.

1. Measure checkout steps

To measure the first checkout step, send a begin_checkout event with the checkout items:

gtag('event', 'begin_checkout', {
  "items": [
    {
      "id": "P12345",
      "name": "Android Warhol T-Shirt",
      "list_name": "Search Results",
      "brand": "Google",
      "category": "Apparel/T-Shirts",
      "variant": "Black",
      "list_position": 1,
      "quantity": 2,
      "price": '2.0'
    }
  ],
  "coupon": ""
});

To measure each subsequent checkout step, send a checkout_progress event with the checkout items:

gtag('event', 'checkout_progress', {
  "items": [
    {
      "id": "P12345",
      "name": "Android Warhol T-Shirt",
      "list_name": "Search Results",
      "brand": "Google",
      "category": "Apparel/T-Shirts",
      "variant": "Black",
      "list_position": 1,
      "quantity": 2,
      "price": '2.0'
    }
  ],
  "coupon": "SUMMER_DISCOUNT"
});

2. Measure checkout options

To measure a checkout option, send a set_checkout_option event with the checkout option:

gtag('event', 'set_checkout_option', {
  "checkout_step": 1,
  "checkout_option": "shipping method",
  "value": "USPS"
});

Measure purchases

To measure a transaction, send a purchase event with the items in the transaction:

gtag('event', 'purchase', {
  "transaction_id": "24.031608523954162",
  "affiliation": "Google online store",
  "value": 23.07,
  "currency": "USD",
  "tax": 1.24,
  "shipping": 0,
  "items": [
    {
      "id": "P12345",
      "name": "Android Warhol T-Shirt",
      "list_name": "Search Results",
      "brand": "Google",
      "category": "Apparel/T-Shirts",
      "variant": "Black",
      "list_position": 1,
      "quantity": 2,
      "price": '2.0'
    },
    {
      "id": "P67890",
      "name": "Flame challenge TShirt",
      "list_name": "Search Results",
      "brand": "MyBrand",
      "category": "Apparel/T-Shirts",
      "variant": "Red",
      "list_position": 2,
      "quantity": 1,
      "price": '3.0'
    }
  ]
});

Measure refunds

To measure a full refund of a transaction, send a refund event with the transaction ID:

gtag('event', 'refund', { "transaction_id": "T12345" })

To measure a partial refund, send a refund event with the transaction ID and the items to be refunded:

gtag('event', 'refund', {
  "transaction_id": "79.18502354114992",
  "affiliation": "Google online store",
  "value": 23.07,
  "currency": "USD",
  "tax": 1.24,
  "shipping": 0,
  "items": [
    {
      "id": "P12345",
      "name": "Android Warhol T-Shirt",
      "list_name": "Search Results",
      "brand": "Google",
      "category": "Apparel/T-Shirts",
      "variant": "Black",
      "list_position": 1,
      "quantity": 2,
      "price": '2.0'
    },
    {
      "id": "P67890",
      "name": "Flame challenge TShirt",
      "list_name": "Search Results",
      "brand": "MyBrand",
      "category": "Apparel/T-Shirts",
      "variant": "Red",
      "list_position": 2,
      "quantity": 1,
      "price": '3.0'
    }
  ]
});