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.

Note: The schema for Ecommerce events is backwards compatible. If you instrumented your site before Google Analytics 4, no changes are required. However, It is strongly recommend that all new implementations use the format in this guide.

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_category2	string	No	The second or second highest level of the item’s category
item_category3	string	No	The third or third highest level of the item’s category
item_category4	string	No	The fourth or fourth highest level of the item’s category
item_category5	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. *Required for purchase and refund events.
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	Yes*	The local currency of the price that is collected. *Required for purchase events.
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 theuser
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

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', {
  currency: 'USD',
  items: [{
    item_id: 'I_12345',
    item_name: 'Android Warhol T-Shirt',
    item_list_name: 'Search Results',
    item_list_id: 'L_12345',
    item_brand: 'Google',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Black',
    index: 1,
    quantity: 2,
    price: 9.99
  }, {
    item_id: 'I_12346',
    item_name: 'Flame challenge T-Shirt',
    item_list_name: 'Search Results',
    item_list_id: 'L_12345',
    item_brand: 'Flame Challenge',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Red',
    index: 2,
    quantity: 1,
    price: 12.99
  }]
});

Measure product clicks

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

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

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', {
  currency: 'USD',
  items: [{
    item_id: 'I_12345',
    item_name: 'Android Warhol T-Shirt',
    item_list_name: 'Search Results',
    item_list_id: 'L_12345',
    item_brand: 'Google',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Black',
    index: 1,
    quantity: 2,
    price: 9.99
  }]
});

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', {
  currency: 'USD',
  items : [{
    item_id: 'I_12345',
    item_name: 'Android Warhol T-Shirt',
    item_list_name: 'Search Results',
    item_list_id: 'L_12345',
    item_brand: 'Google',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Black',
    index: 1,
    quantity: 2,
    price: 9.99
  }]
});

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', {
  currency: 'USD',
  items: [{
    item_id: 'I_12345',
    item_name: 'Android Warhol T-Shirt',
    item_list_name: 'Search Results',
    item_list_id: 'L_12345',
    item_brand: 'Google',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Black',
    index: 1,
    quantity: 2,
    price: 9.99
  }]
});

Measure promotion impressions

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

gtag('event', 'view_promotion', {
  currency: 'USD',
  items: [{
    item_id: 'I_12345',
    item_name: 'Android Warhol T-Shirt',
    promotion_id: 'P_12345',
    promotion_name: 'summer_promo',
    creative_name: 'in_store_summer',
    creative_slot: 'featured_shirt',
    location_id: 'hero_banner',
    item_brand: 'Google',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Black',
    index: 1,
    quantity: 2,
    price: 9.99
  }]
});

Measure promotion clicks

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

gtag('event', 'select_promotion', {
  currency: 'USD',
  items: [{
    item_id: 'I_12345',
    item_name: 'Android Warhol T-Shirt',
    promotion_id: 'P_12345',
    promotion_name: 'summer_promo',
    creative_name: 'in_store_summer',
    creative_slot: 'featured_shirt',
    location_id: 'hero_banner',
    item_brand: 'Google',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Black',
    index: 1,
    quantity: 2,
    price: 9.99
  }]
});

Measure checkouts

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

gtag('event', 'begin_checkout', {
  currency: 'USD',
  items: [{
    item_id: 'I_12345',
    item_name: 'Android Warhol T-Shirt',
    item_list_name: 'Search Results',
    item_list_id: 'L_12345',
    item_brand: 'Google',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Black',
    index: 1,
    quantity: 2,
    price: 9.99,
    affiliation: 'Google Online Store'
  }, {
    item_id: 'I_12346',
    item_name: 'Flame challenge T-Shirt',
    item_list_name: 'Search Results',
    item_list_id: 'L_12345',
    item_brand: 'Flame Challenge',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Red',
    index: 2,
    quantity: 1,
    price: 12.99,
    affiliation: 'Google Online Store',
    coupon: '5OFFRED'
  }]
});

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: 32.97,
  currency: 'USD',
  items: [{
    item_id: 'I_12345',
    item_name: 'Android Warhol T-Shirt',
    item_list_name: 'Search Results',
    item_list_id: 'L_12345',
    item_brand: 'Google',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Black',
    index: 1,
    quantity: 2,
    price: 9.99,
    affiliation: 'Google Online Store'
  }, {
    item_id: 'I_12346',
    item_name: 'Flame challenge T-Shirt',
    item_list_name: 'Search Results',
    item_list_id: 'L_12345',
    item_brand: 'Flame Challenge',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Red',
    index: 2,
    quantity: 1,
    price: 12.99,
    affiliation: 'Google Online Store',
    coupon: '5OFFRED'
  }]
});

Measure purchases

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

Note: currency is a required parameter for a purchase event.

gtag('event', 'purchase', {
  transaction_id: 'T_12345',
  value: 36.27,
  currency: 'USD',
  tax: 3.30,
  shipping: 0,
  coupon: 'free_shipping',
  items: [{
    item_id: 'I_12345',
    item_name: 'Android Warhol T-Shirt',
    item_list_name: 'Search Results',
    item_list_id: 'L_12345',
    item_brand: 'Google',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Black',
    index: 1,
    quantity: 2,
    price: 9.99,
    affiliation: 'Google Online Store'
  }, {
    item_id: 'I_12346',
    item_name: 'Flame challenge T-Shirt',
    item_list_name: 'Search Results',
    item_list_id: 'L_12345',
    item_brand: 'Flame Challenge',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Red',
    index: 2,
    quantity: 1,
    price: 12.99,
    affiliation: 'Google Online Store',
    coupon: '5OFFRED'
  }]
});

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: 'T_12345',
  value: 14.29,
  currency: 'USD',
  tax: 1.30,
  items: [{
    item_id: 'I_12346',
    item_name: 'Flame challenge T-Shirt',
    item_list_name: 'Search Results',
    item_list_id: 'L_12345',
    item_brand: 'Flame Challenge',
    item_category: 'Apparel/T-Shirts',
    item_variant: 'Red',
    index: 2,
    quantity: 1,
    price: 12.99,
    affiliation: 'Google Online Store',
  }]
});