Enhanced ecommerce with gtag.js

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.

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 number 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 number 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 number No Tax amount
shipping number 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.

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