Ecommerce with gtag.js

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

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

View/impression data

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

Item parameter Data type Required Description
item_id string Yes* Unique ID/SKU for the item
item_name string Yes* The Item’s name
item_list_name string No The list in which the item was presented to the user
item_list_id string No The list id in which the item was presented to the user
index integer No The list index (or position) in which the item was presented to the user
item_brand string No Brand of the item
item_category string No The category or the highest level of the item’s category
item_category2 string No The second highest level of the item’s category or an alternative category
item_category3 string No The third highest level of the item’s category or an alternative category
item_category4 string No The fourth highest level of the item’s category or an alternative category
item_category5 string No The fifth highest level of the item’s category or an alternative category
item_variant string No The item’s variant name or description (e.g. it’s color or version name)
affiliation string No The store or affiliation from which this event occurred
discount float No Any discount associated with the item
coupon string No Any coupon associated with the item
price number No Purchase price of the item

* Either item_id or item_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
item_id string Yes* Unique ID/SKU for the item
item_name string Yes* Item name
item_brand string No Brand of the item
item_category string No The first or highest level of the item’s category
item_category_2 string No The second or second highest level of the item’s category
item_category_3 string No The third or third highest level of the item’s category
item_category_4 string No The fourth or fourth highest level of the item’s category
item_category_5 string No The fifth or fifth highest level of the item’s category
item_variant string No Item variant
affiliation string No The store or affiliation from which this event occurred
discount float No Any discount associated with the item
coupon string No Any coupon associated with the item
price number No Purchase price of the item
currency string No The local currency of the price that is collected
quantity integer No The quantity of a given item

* Either item_id or item_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
promotion_id string Yes* The id of any promotion associated with the event
promotion_name string Yes* The name of any promotion associated with the event
creative_name string No The name of the creative for the promotion associated with the event
creative_slot string No The creative slot of the promotion associated with the event when it was presented to the user
location_id string No The location of the promotion associated with the event when it was presented to the user

* Either promotion_id or promotion_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
currency string No The local currency of the price that is collected
tax number No Tax amount
shipping number No Shipping cost
items array No The array containing the associated item/product data for any event (e.g. views, cart events, purchases and refunds)
shipping_tier string No The tier of shipping for the purchase
payment_type string No The type of payment used for the purchase
coupon string No Coupon code for a purchasable item
promotion_id string No The id of any promotion associated with the event
promotion_name string No The name of any promotion associated with the event
creative_name string No The name of the creative for the promotion associated with the event
creative_slot string No The creative slot of the promotion associated with the event when it was presented to the user
location_id string No The location of the promotion associated with the event when it was presented to the user
item_list_name string No The list in which the item was presented to the user
item_list_id string No The list id in which the item was presented to the user

* Required for purchase or refund.

Product, list, and promotion actions

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

Event Description
view_item_list An impression of a product/item list.
select_item A click on a product/item list for one or more products.
view_promotion An impression of an internal promotion.
select_promotion A click on an internal promotion.
view_item A view of product details.
add_to_cart Adding one or more products to a shopping cart.
add_to_wishlist Adding one or more products to a wish list.
remove_from_cart Removing one or more products from a shopping cart.
view_cart A view of a user’s shopping cart.
begin_checkout Initiating the checkout process for one or more products.
add_shipping_info Adding ones shipping info during the checkout flow.
add_payment_info Adding ones payment info during the checkout flow.
purchase The sale of one or more products.
refund The refund of one or more products.

Measure product impressions

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

gtag('event', 'view_item_list', {
  "items": [
    {
      "item_id": "P12345",
      "item_name": "Android Warhol T-Shirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "Google",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Black",
      "index": 1,
      "quantity": 2,
      "price": '2.0'
    },
    {
      "item_id": "P67890",
      "item_name": "Flame challenge TShirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "MyBrand",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Red",
      "index": 2,
      "quantity": 1,
      "price": '3.0'
    }
  ]
});

Measure product clicks

To measure a product list clicks, send a select_content event and provide the product information:

gtag('event', 'select_item', {
  "items": [
    {
      "item_id": "P12345",
      "item_name": "Android Warhol T-Shirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "Google",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Black",
      "index": 1,
      "quantity": 2,
      "price": '2.0'
    }
  ]
});

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": [
    {
      "item_id": "P12345",
      "item_name": "Android Warhol T-Shirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "Google",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Black",
      "index": 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": [
    {
      "item_id": "P12345",
      "item_name": "Android Warhol T-Shirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "Google",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Black",
      "index": 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": [
    {
      "item_id": "P12345",
      "item_name": "Android Warhol T-Shirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "Google",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Black",
      "index": 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', {
  "items": [
    {
      "item_id": "P12345",
      "item_name": "Android Warhol T-Shirt",
      "promotion_id": "abc123",
      "promotion_name": "summer_promo",
      "creative_name": "instore_suummer",
      "creative_slot": "1",
      "location_id": "hero_banner",
      "item_brand": "Google",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Black",
      "index": 1,
      "quantity": 2,
      "price": '2.0'
    }
  ]
});

Measure promotion clicks

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

gtag('event', 'select_promotion', {
  "items": [
    {
      "item_id": "P12345",
      "item_name": "Android Warhol T-Shirt",
      "promotion_id": "abc123",
      "promotion_name": "summer_promo",
      "creative_name": "instore_suummer",
      "creative_slot": "1",
      "location_id": "hero_banner",
      "item_brand": "Google",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Black",
      "index": 1,
      "quantity": 2,
      "price": '2.0'
    }
  ]
});

Measure checkouts

To measure users entering the checkout flow, send a begin_checkout event with the checkout items:

gtag('event', 'begin_checkout', {
"items": [
    {
      "item_id": "P12345",
      "item_name": "Android Warhol T-Shirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "Google",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Black",
      "index": 1,
      "quantity": 2,
      "price": '2.0',
      "affiliation": "Google online store"
    },
    {
      "item_id": "P67890",
      "item_name": "Flame challenge TShirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "MyBrand",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Red",
      "index": 2,
      "quantity": 1,
      "price": '3.0',
      "affiliation": "Google online store",
      "coupon": "5off_redshirts"
    }
  ]
});

Measure the addition of payment information

To measure users that enter their payment information, send an add_payment_info event along with the payment_type entered:

gtag('event', 'add_payment_info', {
  "payment_type": "google_pay",
  "value": 23.07,
  "currency": "USD",
"items": [
    {
      "item_id": "P12345",
      "item_name": "Android Warhol T-Shirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "Google",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Black",
      "index": 1,
      "quantity": 2,
      "price": '2.0',
      "affiliation": "Google online store"
    },
    {
      "item_id": "P67890",
      "item_name": "Flame challenge TShirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "MyBrand",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Red",
      "index": 2,
      "quantity": 1,
      "price": '3.0',
      "affiliation": "Google online store",
      "coupon": "5off_redshirts"
    }
  ]
});

Measure purchases

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

gtag('event', 'purchase', {
  "transaction_id": "24.031608523954162",
  "value": 23.07,
  "currency": "USD",
  "tax": 1.24,
  "shipping": 0,
  "coupon": "free_shipping",
  "items": [
    {
      "item_id": "P12345",
      "item_name": "Android Warhol T-Shirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "Google",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Black",
      "index": 1,
      "quantity": 2,
      "price": '2.0',
      "affiliation": "Google online store"
    },
    {
      "item_id": "P67890",
      "item_name": "Flame challenge TShirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "MyBrand",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Red",
      "index": 2,
      "quantity": 1,
      "price": '3.0',
      "affiliation": "Google online store",
      "coupon": "5off_redshirts"
    }
  ]
});

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",
  "value": 23.07,
  "currency": "USD",
  "tax": 1.24,
  "shipping": 0,
  "coupon": "free_shipping",
  "items": [
    {
      "item_id": "P12345",
      "item_name": "Android Warhol T-Shirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "Google",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Black",
      "index": 1,
      "quantity": 2,
      "price": '2.0',
      "affiliation": "Google online store",
    },
    {
      "item_id": "P67890",
      "item_name": "Flame challenge TShirt",
      "item_list_name": "Search Results",
      "item_list_id": "list123",
      "item_brand": "MyBrand",
      "item_category": "Apparel/T-Shirts",
      "item_variant": "Red",
      "index": 2,
      "quantity": 1,
      "price": '3.0',
      "affiliation": "Google online store",
    }
  ]
});