Overview

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

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.

For a list of ecommerce related events, refer to the gtag.js Event reference.

Enhanced Ecommerce Data Types and Actions

There are multiple types of ecommerce data you can send:

Impression Data

Represents information about a product that has been viewed. It is referred to as an impressionFieldObject and contains the following values:

Key Value Type Required Description
id text *Yes

The product ID or SKU (e.g. P67890).

* One of id or name must be set.

name text *Yes

The name of the product (e.g. Android T-Shirt).

* One of id or name must be set.

list_name text No The list or collection to which the product belongs (e.g. Search Results)
brand text No The brand associated with the product (e.g. Google).
category text No The category to which the product belongs (e.g. Apparel). Use / as a delimiter to specify up to 5-levels of hierarchy (e.g. Apparel/Men/T-Shirts).
variant text No The variant of the product (e.g. Black).
list_position integer No The product's position in a list or collection (e.g. 2).
price number No The price of a product (e.g. 29.20).

Product Data

Product data represents individual products that were viewed, added to the shopping cart, etc. It is referred to as a productFieldObject and contains the following values:

Key Value Type Required Description
id text *Yes

The product ID or SKU (e.g. P67890).

* One of id or name must be set.

name text *Yes

The name of the product (e.g. Android T-Shirt).

* One of id or name must be set.

brand text No The brand associated with the product (e.g. Google).
category text No The category to which the product belongs (e.g. Apparel). Use / as a delimiter to specify up to 5-levels of hierarchy (e.g. Apparel/Men/T-Shirts).
variant text No The variant of the product (e.g. Black).
price number No The price of a product (e.g. 29.20).
quantity integer No The quantity of a product (e.g. 2).
coupon text No The coupon code associated with a product (e.g. SUMMER_SALE13).
list_position integer No The product's position in a list or collection (e.g. 2).

Promotion Data

Represents information about a promotion that has been viewed. It is referred to a promoFieldObject and contains the following values:

Key Value Type Required Description
id text *Yes

The promotion ID (e.g. PROMO_1234).

* One of id or name must be set.

name text *Yes

The name of the promotion (e.g. Summer Sale).

* One of id or name must be set.

creative_name text No The name of the creative (e.g. summer_banner2).
creative_slot text No The name of the creative slot (e.g. banner_slot_1).

Action Data

Represents information about an ecommerce related action that has taken place. It is referred to as an actionFieldObject and contains the following values:

Key Value Type Required Description
id text *Yes

The transaction ID (e.g. T1234).

* Required if the action type is purchase or refund

affiliation text No The store or affiliation from which this transaction occurred (e.g. Google Store).
value number No Value (i.e. revenue) associated with the event.
tax number No The total tax associated with the transaction.
shipping number No The shipping cost associated with the transaction.
items array No The array containing the associated products.
checkout_step integer No A number representing a step in the checkout process.
checkout_option text No Checkout option (i.e. selected payment method).
Key Value Type Required Description
coupon string No Coupon code for a purchasable item.

Product and Promotion Actions

Actions 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 Remove 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.
refund The sale of one or more products.
view_refund The refund of one or more products.
view_promotion A click on an internal promotion.

Examples

Measure product impressions

To measure product impressions, send a view_item_list with the product information:

gtag('event', 'view_item_list', {
  "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
    },
    {
      "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
    }
  ]
});

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_name": "Search Results",
      "brand": "Google",
      "category": "Apparel/T-Shirts",
      "variant": "Black",
      "list_position": 1,
      "quantity": 2,
      "price": 2
    }
  ]
});

Measure product detail views

After clicking a product listing, a user might view the product details page. To measure product detail views, 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 carts

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 checkouts

To measure each step in a checkout process:

  1. Add measurement code to measure each step of the checkout process.
  2. If applicable, add measurement code to record 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": 3
});

Measure promotion impressions

To measure promotion impressions, send a view_promotion event with promotion information:

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 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'
    }
  ]
});