The enhanced ecommerce plug-in for analytics.js enables the measurement of user interactions with products on ecommerce websites across the user's shopping experience, including: product impressions, product clicks, viewing product details, adding a product to a shopping cart, initiating the checkout process, transactions, and refunds.
Migration and Compatibility with Ecommerce Plug-in (ecommerce.js)
If you've already implemented Ecommerce measurement and want to start using Enhanced Ecommerce there are two main options:
Use a new property
You can add an additional tracker for a newly created property and tag/enable Enhanced Ecommerce for the new property. See Working with Multiple Tracking Objects for details on how to send data to multiple properties from a single page.
Migrate an existing property
To migrate from the ecommerce plug-in to the enhanced ecommerce plug-in, current analytics.js users should remove and replace references with enhanced ecommerce code.
If you are currently using ga.js, you will need to first migrate to analytics.js before using the enhanced ecommerce plug-in.
Transaction and item data previously collected using the ecommerce.js plug-in will not be affected by the migration and will remain available in the properties and profiles to which they were originally sent.
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 |
name |
text | *Yes |
The name of the product (e.g. Android T-Shirt).
* One of |
list |
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). |
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 |
text | *Yes |
The name of the product (e.g. Android T-Shirt).
* One of id or |
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). |
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 |
name |
text | *Yes |
The name of the promotion (e.g. Summer Sale).
* One of |
creative |
text | No | The creative associated with the promotion (e.g. summer_banner2). |
position |
text | No | The position of the creative (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 |
affiliation |
text | No | The store or affiliation from which this transaction occurred (e.g. Google Store). |
revenue |
number | No |
Specifies the total revenue or grand total associated with the transaction (e.g. 11.99). This value may include shipping, tax costs, or other adjustments to total revenue that you want to include as part of your revenue calculations. |
tax |
number | No | The total tax associated with the transaction. |
shipping |
number | No | The shipping cost associated with the transaction. |
coupon |
text | No | The transaction coupon redeemed with the transaction. |
list |
text | No | The list that the associated products belong to. Optional. |
step |
integer | No | A number representing a step in the checkout process. Optional on `checkout` actions. |
option |
text | No |
Additional field for checkout and
checkout_option actions that can describe option information
on the checkout page, like selected payment method.
|
Product and Promotion Actions
Actions specify how to interpret product and promotion data that you send to Google Analytics.
Action | Description |
---|---|
click |
A click on a product or product link for one or more products. |
detail |
A view of product details. |
add |
Adding one or more products to a shopping cart. |
remove |
Remove one or more products from a shopping cart. |
checkout |
Initiating the checkout process for one or more products. |
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. |
promo_click |
A click on an internal promotion. |
Implementation
The following sections describe how to implement the enhanced ecommerce plug-in to measure ecommerce activity on a website with the analytics.js library.
Load the Ecommerce Plugin
To reduce the size of the analytics.js library, enhanced ecommerce is not provided in the default library. Instead it is provided as a plugin module that must be loaded before being used.
To load the enhanced ecommerce plugin, use the following command:
ga('require', 'ec');
This command must occur after you create your tracker object and before you use any of the enhanced ecommerce specific functionality.
Sending Enhanced Ecommerce Data
Once loaded, a couple of new commands specific to enhanced ecommerce will be added to the default tracker and you can begin sending ecommerce data.
- Measuring Ecommerce Activities
- Measuring Transactions
- Measuring Refunds
- Measuring the Checkout Process
- Measuring Internal Promotions
Measuring Ecommerce Activities
A typical enhanced ecommerce implementation will measure product impressions, and any of the following actions:
- Clicks on a product link.
- Viewing product details.
- Impressions and clicks of internal promotions.
- Adding/removing a product from a shopping cart.
- Initiating the checkout process for a product.
- Purchases and refunds.
Measuring Impressions
Product impressions are measured using the ec:addImpression
command. Details
about the product are added in an impressionFieldObject
.
For example, the following code measures the impression of a product in a list of search results:
ga('ec:addImpression', { // Provide product details in an impressionFieldObject.
'id': 'P12345', // Product ID (string).
'name': 'Android Warhol T-Shirt', // Product name (string).
'category': 'Apparel/T-Shirts', // Product category (string).
'brand': 'Google', // Product brand (string).
'variant': 'Black', // Product variant (string).
'list': 'Search Results', // Product list (string).
'position': 1, // Product position (number).
'dimension1': 'Member' // Custom dimension (string).
});
An impressionFieldObject
must have a name
or id
value. All other values
are optional and don't need to be set.
Measuring Actions
Actions are measured by using the ec:addProduct
command with a
productFieldObject
to add product details, and the
ec:setAction
command to specify the action being performed.
For example, the following code measures a click on a product link displayed in a list of search results:
ga('ec:addProduct', { // Provide product details in a productFieldObject.
'id': 'P12345', // Product ID (string).
'name': 'Android Warhol T-Shirt', // Product name (string).
'category': 'Apparel', // Product category (string).
'brand': 'Google', // Product brand (string).
'variant': 'Black', // Product variant (string).
'position': 1, // Product position (number).
'dimension1': 'Member' // Custom dimension (string).
});
ga('ec:setAction', 'click', { // click action.
'list': 'Search Results' // Product list (string).
});
A productFieldObject
must have a name
or id
value. All other values are
optional and don't need to be set.
Combining Impressions and Actions
In cases where you have both product impressions and an action, it is possible to combine and measure this in a single hit.
The example below shows how to measure a product detail view with a related products section:
// The impression from a Related Products section.
ga('ec:addImpression', { // Provide product details in an impressionFieldObject.
'id': 'P12345', // Product ID (string).
'name': 'Android Warhol T-Shirt', // Product name (string).
'category': 'Apparel/T-Shirts', // Product category (string).
'brand': 'Google', // Product brand (string).
'variant': 'Black', // Product variant (string).
'list': 'Related Products', // Product list (string).
'position': 1 // Product position (number).
});
// The product being viewed.
ga('ec:addProduct', { // Provide product details in an productFieldObject.
'id': 'P67890', // Product ID (string).
'name': 'YouTube Organic T-Shirt', // Product name (string).
'category': 'Apparel/T-Shirts', // Product category (string).
'brand': 'YouTube', // Product brand (string).
'variant': 'gray', // Product variant (string).
'position': 2 // Product position (number).
});
ga('ec:setAction', 'detail'); // Detail action.
Measuring Transactions
Measure a transaction by using the ec:setAction
command and setting the
action type to purchase
. Transaction level details like total
revenue, tax, and shipping are provided in an
actionFieldObject
:
ga('ec:addProduct', { // Provide product details in an productFieldObject.
'id': 'P12345', // Product ID (string).
'name': 'Android Warhol T-Shirt', // Product name (string).
'category': 'Apparel', // Product category (string).
'brand': 'Google', // Product brand (string).
'variant': 'black', // Product variant (string).
'price': '29.20', // Product price (number).
'coupon': 'APPARELSALE', // Product coupon (string).
'quantity': 1 // Product quantity (number).
});
ga('ec:setAction', 'purchase', { // Transaction details are provided in an actionFieldObject.
'id': 'T12345', // (Required) Transaction id (string).
'affiliation': 'Google Store - Online', // Affiliation (string).
'revenue': '37.39', // Revenue (number).
'tax': '2.85', // Tax (number).
'shipping': '5.34', // Shipping (number).
'coupon': 'SUMMER2013' // Transaction coupon (string).
});
An actionFieldObject
must have an id
value if the action type is purchase
or refund
. All other values are optional and don't need to be set.
Measuring Refunds
To refund an entire transaction, set a refund
action and provide the
transaction ID:
// Refund an entire transaction.
ga('ec:setAction', 'refund', {
// Transaction ID is only required field for full refund.
'id': 'T12345'
});
If a matching transaction is not found, the refund
hit will not be processed.
To measure a partial refund, set a refund
action and specify the transaction
ID, product ID(s), and product quantities to be refunded:
// Refund a single product.
ga('ec:addProduct', {
'id': 'P12345', // Product ID is required for partial refund.
'quantity': 1 // Quantity is required for partial refund.
});
ga('ec:setAction', 'refund', {
'id': 'T12345', // Transaction ID is required for partial refund.
});
Using Non-Interaction Events for Refunds
If you need to send refund data using an event and the event is not part of normally measured onsite behavior (i.e. not user initiated), then it’s recommended that you send a non-interaction event. This will prevent metrics such as bounce rate, time on site, etc. from being affected by the event. For example:
ga('send', 'event', 'Ecommerce', 'Refund', {'nonInteraction': 1});
Measuring the Checkout Process
To measure each step in a checkout process:
- Add code to measure each step of the checkout process.
- If applicable, add code to measure checkout options.
- Optionally set user-friendly step names for the checkout funnel report by configuring Ecommerce Settings in the admin section of the web interface.
1. Measuring Checkout Steps
For each step in your checkout process, you’ll need to implement the corresponding code to send data to Google Analytics:
step
FieldFor each checkout step that you measure you should include a
step
value. This value is used to map your checkout actions to the labels you configured for each step in Ecommerce Settings.option
FieldIf you have additional information about the given checkout step at the time the step is measured, you can set the
option
field with acheckout
action to capture this information. For example, the default payment type for the user (e.g.Visa
).Measuring a Checkout Step
To measure a checkout step, use
ec:addProduct
for each product, andec:setAction
indicate a checkout. If applicable,ec:setAction
can take an additionalactionFieldObject
to describe the checkout step with astep
and anoption
.The following example shows how to measure the first step of a checkout process, with a single product, and some additional information about the payment type:
ga('ec:addProduct', { // Provide product details in an productFieldObject. 'id': 'P12345', // Product ID (string). 'name': 'Android Warhol T-Shirt', // Product name (string). 'category': 'Apparel', // Product category (string). 'brand': 'Google', // Product brand (string). 'variant': 'black', // Product variant (string). 'price': '29.20', // Product price (number). 'quantity': 1 // Product quantity (number). }); // Add the step number and additional info about the checkout to the action. ga('ec:setAction','checkout', { 'step': 1, 'option': 'Visa' });
2. Measuring Checkout Options
Checkout options allow you to measure additional information about the state of the checkout. This is useful in cases where you’ve measured a checkout step during the initial pageview but additional information about the same checkout step is available after a user selected option has been set. For example, the user selects a shipping method.
To measure a checkout option, use ec:setAction
to indicate a checkout_option
and include the step number, and the option description.
You’ll likely want to measure this action once the user has clicked to move on to the next step in the checkout process. For example:
// (On "Next" button click)
ga('ec:setAction', 'checkout_option', {'step': 2, 'option': 'FedEx'});
ga('send', 'event', 'Checkout', 'Option', {
hitCallback: function() {
// advance to next page
},
});
3. Checkout Funnel Configuration
Each step in your checkout process can be given a descriptive name that will be used in reports. To configure these names, visit the Admin section of the Google Analytics Web Interface, select the view (profile) and click on Ecommerce Settings. Follow the Ecommerce set-up instructions to label each checkout step you intend to measure.

Measuring Internal Promotions
The enhanced ecommerce plug-in includes support for measuring impressions and clicks of internal promotions, such as banners displayed to promote a sale on another section of a website.
Promotion Impressions
Internal promotion impressions are generally measured when the page loads and
are sent with the initial pageview using the ec:addPromo
command. For example:
ga('ec:addPromo', { // Promo details provided in a promoFieldObject.
'id': 'PROMO_1234', // Promotion ID. Required (string).
'name': 'Summer Sale', // Promotion name (string).
'creative': 'summer_banner2', // Creative (string).
'position': 'banner_slot1' // Position (string).
});
Promotion Clicks
Clicks on internal promotions can be measured by setting the promo_click
action. For example:
// Identify the promotion that was clicked.
ga('ec:addPromo', {
'id': 'PROMO_1234',
'name': 'Summer Sale',
'creative': 'summer_banner2',
'position': 'banner_slot1'
});
// Send the promo_click action with an event.
ga('ec:setAction', 'promo_click');
ga('send', 'event', 'Internal Promotions', 'click', 'Summer Sale');
For example, to measure a product detail page with an impression and a promo click, first send product and impression data with the initial pageview, then send promo click data in a separate event:
// 1. Send product and impression data with pageview.
ga('ec:addProduct', {
'id': 'P12345', // Product ID (string).
'name': 'Android Warhol T-Shirt', // Product name (string).
'category': 'Apparel', // Product category (string).
'brand': 'Google', // Product brand (string).
'variant': 'Black', // Product variant (string).
'position': 1, // Product position (number).
});
// The impression from the Related Products section.
ga('ec:addImpression', {
'id': 'P12345', // Product ID (string).
'name': 'Android Warhol T-Shirt', // Product name (string).
'category': 'Apparel/T-Shirts', // Product category (string).
'brand': 'Google', // Product brand (string).
'variant': 'Black', // Product variant (string).
'list': 'Related Products', // Product list (string).
'position': 1, // Product position (number).
});
ga('ec:setAction', 'detail'); // Detail action.
ga('send', 'pageview'); // Send the product data with initial pageview.
// 2. Send the promo click data when the promo click occurs.
// Call this function when promo click occurs.
function onPromoClick() {
ga('ec:addPromo', {
'id': 'PROMO_1234',
'name': 'Summer Sale',
'creative': 'summer_banner2',
'position': 'banner_slot1'
});
// Send the promo_click action with an event.
ga('ec:setAction', 'promo_click');
ga('send', 'event', 'Internal Promotions', 'click', 'Summer Sale');
}
A promoFieldObject
must have a name
or id
value. All
other values are optional and don't need to be set.
Complete Example
The code snippets below show how the ecommerce lifecycle of a single product can be measured from initial impression to transaction using the enhanced ecommerce plug-in.
Measuring a Product Impression
In this example, a user first views the product in a list of search results. To
measure this product impression, use the ec:addImpression
command and provide
the product details in an impressionFieldObject
:
ga('create', 'UA-XXXXX-Y');
ga('require', 'ec');
ga('ec:addImpression', {
'id': 'P12345', // Product details are provided in an impressionFieldObject.
'name': 'Android Warhol T-Shirt',
'category': 'Apparel/T-Shirts',
'brand': 'Google',
'variant': 'black',
'list': 'Search Results',
'position': 1 // 'position' indicates the product position in the list.
});
ga('ec:addImpression', {
'id': 'P67890',
'name': 'YouTube Organic T-Shirt',
'category': 'Apparel/T-Shirts',
'brand': 'YouTube',
'variant': 'gray',
'list': 'Search Results',
'position': 2
});
ga('send', 'pageview'); // Send product impressions with initial pageview.
Measuring a Product Click
Next, a user expresses interest in this particular product by clicking on the product listing to view more details.
To measure that product click, use ec:addProduct
and ec:setAction
:
// Called when a link to a product is clicked.
function onProductClick() {
ga('ec:addProduct', {
'id': 'P12345',
'name': 'Android Warhol T-Shirt',
'category': 'Apparel',
'brand': 'Google',
'variant': 'black',
'position': 1
});
ga('ec:setAction', 'click', {list: 'Search Results'});
// Send click with an event, then send user to product page.
ga('send', 'event', 'UX', 'click', 'Results', {
hitCallback: function() {
document.location = '/product_details?id=P12345';
}
});
}
The product link could then be implemented like this:
<a href="/next-page.html"
onclick="onProductClick(); return !ga.loaded;">
Android Warhol T-Shirt
</a>
Measuring a Product Details View
After clicking on the product listing, a user views the product details page.
To measure this product details view, use ec:addProduct
and ec:setAction
to
specify a detail
action:
ga('create', 'UA-XXXXX-Y');
ga('require', 'ec');
ga('ec:addProduct', {
'id': 'P12345',
'name': 'Android Warhol T-Shirt',
'category': 'Apparel',
'brand': 'Google',
'variant': 'black'
});
ga('ec:setAction', 'detail');
ga('send', 'pageview'); // Send product details view with the initial pageview.
Measuring an Addition or Removal from Cart
The user expresses intent to buy the item by adding it to a shopping cart.
To measure the addition or removal of a product from a shopping cart, use
ec:addProduct
and set the type add
or remove
:
// Called when a product is added to a shopping cart.
function addToCart(product) {
ga('ec:addProduct', {
'id': product.id,
'name': product.name,
'category': product.category,
'brand': product.brand,
'variant': product.variant,
'price': product.price,
'quantity': product.qty
});
ga('ec:setAction', 'add');
ga('send', 'event', 'UX', 'click', 'add to cart'); // Send data using an event.
}
Measuring Checkout Process
Now the user is ready to begin the checkout process, which in this example includes two steps, each on separate pages:
- Add payment details (payment.html).
- Add shipping details (shipping.html).
If applicable, ensure you have properly configured a checkout-funnel in the Web Interface Admin, under Ecommerce Settings. For example:

Step 1 - Payment
To measure the first step of the checkout, use ec:addProduct
for each product
in the shopping cart, and ec:setAction
to indicate a checkout
.
ec:setAction
takes an actionFieldObject
to describe the checkout step with a
number and additional information about the default payment type for this user
has been included using the option
field:
ga('create', 'UA-XXXXX-Y');
ga('require', 'ec');
/**
* Called when the user begins the checkout process.
* @param {Array} cart An array representing the user's shopping cart.
*/
function checkout(cart) {
for(var i = 0; i < cart.length; i++) {
var product = cart[i];
ga('ec:addProduct', {
'id': product.id,
'name': product.name,
'category': product.category,
'brand': product.brand,
'variant': product.variant,
'price': product.price,
'quantity': product.qty
});
}
}
// In the case of checkout actions, an additional actionFieldObject can
// specify a checkout step and option.
ga('ec:setAction','checkout', {
'step': 1, // A value of 1 indicates this action is first checkout step.
'option': 'Visa' // Used to specify additional info about a checkout stage, e.g. payment method.
});
ga('send', 'pageview'); // Pageview for payment.html
Step 2 - Shipping
To measure the second step of the checkout, use ec:addProduct
for each product
in the shopping cart, and ec:setAction
to indicate a checkout. In this case we
don’t have additional information about the shipping option selected when the
initial pageview is sent so this will be handled separately using the
ec:setAction
to indicate a checkout_option
.
// Measure checkout step 2:
ga('create', 'UA-XXXXX-Y');
ga('require', 'ec');
/**
* Called when the user begins the checkout process.
* @param {Array} cart An array representing the user's shopping cart.
*/
function checkout(cart) {
for(var i = 0; i < cart.length; i++) {
var product = cart[i];
ga('ec:addProduct', {
'id': product.id,
'name': product.name,
'category': product.category,
'brand': product.brand,
'variant': product.variant,
'price': product.price,
'quantity': product.qty
});
}
}
ga('ec:setAction','checkout', {'step': 2});
ga('send', 'pageview'); // Pageview for shipping.html
// Called when user has completed shipping options.
function onShippingComplete(stepNumber, shippingOption) {
ga('ec:setAction', 'checkout_option', {
'step': stepNumber,
'option': shippingOption
});
ga('send', 'event', 'Checkout', 'Option', {
hitCallback: function() {
// Advance to next page.
}
});
}
The form could then be implemented like this:
<a href="/next-page.html"
onclick="onShippingComplete(2, 'FedEx'); return !ga.loaded;">
Continue
</a>
Measuring a Transaction
Lastly, the user completes the checkout process and submits their purchase.
To measure the sale of one or more products, use ec:addProduct
to add each
product, then ec:setAction
to specify a purchase
. Transaction level
information like total revenue, tax, etc. can be specified via an
actionFieldObject
. For example:
ga('create', 'UA-XXXXX-Y');
ga('require', 'ec');
ga('ec:addProduct', {
'id': 'P12345',
'name': 'Android Warhol T-Shirt',
'category': 'Apparel',
'brand': 'Google',
'variant': 'black',
'price': '29.20',
'quantity': 1
});
// Transaction level information is provided via an actionFieldObject.
ga('ec:setAction', 'purchase', {
'id': 'T12345',
'affiliation': 'Google Store - Online',
'revenue': '37.39',
'tax': '2.85',
'shipping': '5.34',
'coupon': 'SUMMER2013' // User added a coupon at checkout.
});
ga('send', 'pageview'); // Send transaction data with initial pageview.
Specifying Local Currencies
By default, you can configure a common, global, currency for all transactions and items through the Google Analytics management web interface. By default, the global currency is used for all items and transactions. For websites that conduct transactions in multiple currencies, the ecommerce plugin allows you to specify the local currency of the transaction.
The local currency must be specified in the ISO 4217
standard. Read the
Currency Codes Reference document for a complete list of supported conversion
currencies.
Local currencies are specified using the currencyCode
tracker property. For
example, this tracker will send currency values as Euros:
ga('create', 'UA-XXXXX-Y');
ga('require', 'ec');
ga('set', 'currencyCode', 'EUR'); // Set currency to Euros.
ga('ec:addProduct', {
'id': 'P12345',
'name': 'Android Warhol T-Shirt',
'category': 'Apparel',
'brand': 'Google',
'variant': 'black',
'price': '21.89',
'quantity': 1
});
ga('ec:setAction', 'purchase', {
id: 'T12345',
affiliation: 'Google Store - Online',
revenue: '28.03',
tax: '2.14',
shipping: '4.00',
coupon: 'SUMMER2013'
});
ga('send', 'pageview');