Transmitting data about products and actions

E-commerce

Tip. Working with the JavaScript API requires knowledge of HTML and JavaScript. If you don't know these languages, contact your website developer or webmaster.

About the data container and its transmission to Yandex Metrica

In E-commerce, every product item is an object that certain actions can be performed on, such as viewing the complete item description or adding it to the basket. This data is transmitted as JavaScript objects containing the action ID and a list of descriptions of items that this action was performed on. In the context of the JavaScript API, we call these objects e-commerce objects.

To transmit data to the Yandex Metrica service as e-commerce objects, you need to put them in a special JavaScript array using the push method. We call this array the data container.

Attention. Don't transmit the data when the user is going to another page on the site. An example is when an onclick event is used on the “Checkout” button. In this case, the next page might load before the tag sends the data to Yandex Metrica. As a result, information about the event is lost.

The data container must be located in the global namespace, and its name must match the name specified during tag configuration or initialization. If the data container is named dataLayer, or the Yandex Metrica counter was initiated with the ecommerce parameter set to true, it is assumed that the data container is the window.dataLayer array.

<script type="text/javascript">
window.dataLayer = window.dataLayer || [];
</script>
...
<script type="text/javascript">
window.dataLayer.push ({...});
</script>

The name of the data container and the structure of the e-commerce objects in it correspond to the same entities in Google Analytics Enhanced E-commerce. This means that if you already set up transmitting data to Google Analytics Enhanced Ecommerce (including via the Global Site Tag) and enabled e-commerce in Yandex Metrica, the latter will start collecting data the same way. Yandex Metrica also supports GA4 Ecommerce and collects data without additional settings.

Restriction. The data container may contain a maximum of 8192 characters.

An e-commerce object has the following format:

window.dataLayer.push({
    "ecommerce": {
        "currencyCode": "RUB",
        "<actionType>" : {
            "actionField" : <actionField>,
            "products" : [<productFieldObject>, <productFieldObject>, ...]
        }
    }
});


Field	Type	Description
`ecommerce` *	Object	Required container field.
`currencyCode`	string	Three-letter ISO 4217 currency code. If a different currency is passed, null values will be sent instead of currencies and amounts.
`<actionType>` *	—	The field name (substituted in place of <actionType>) is the identifier of an action performed with a set of products. Possible values: `detail` — Viewing the full item description (product card). `add` — Adding an item to the basket. `remove` — Removing an item from the basket. `purchase` — Purchasing. If information about removing the item was transmitted to Yandex Metrica, the report might show a negative number of items (the total is calculated by subtracting the number of deleted items from the total number of added items). If the price of the item was transmitted, it might also have a negative value in the report.
`actionField` **	Object	<actionField> type of object. Additional data describing the action performed. Processed only if the action is a purchase (`<actionType>` — `purchase`).
`products` *	Array	List of descriptions of items that the specified action was performed on. Item descriptions are <productFieldObject> objects.


Field	Type	Description
`ecommerce` *	Object	Required container field.
`currencyCode`	string	Three-letter ISO 4217 currency code. If a different currency is passed, null values will be sent instead of currencies and amounts.
`<actionType>` *	—	The field name (substituted in place of <actionType>) is the identifier of an action performed with a set of products. Possible values: `detail` — Viewing the full item description (product card). `add` — Adding an item to the basket. `remove` — Removing an item from the basket. `purchase` — Purchasing. If information about removing the item was transmitted to Yandex Metrica, the report might show a negative number of items (the total is calculated by subtracting the number of deleted items from the total number of added items). If the price of the item was transmitted, it might also have a negative value in the report.
`actionField` **	Object	<actionField> type of object. Additional data describing the action performed. Processed only if the action is a purchase (`<actionType>` — `purchase`).
`products` *	Array	List of descriptions of items that the specified action was performed on. Item descriptions are <productFieldObject> objects.

^* Required parameter.

^** Required parameter for transmitting purchase information.

Item data

An object describing a particular item.

The structure of the object describing the item is denoted as <productFieldObject>.

Object field
Field	Type	Description
`id` *	string	Item ID. For example, the SKU. You must specify either "name" or "id"
`name` *	string	Name of the product. For example, "T-shirt" You must specify either "name" or "id"
`brand`	string	The brand or trademark associated with the item. For example, "Yandex"
`category`	string	The category the item belongs to. The hierarchy of categories supports up to 5 nesting levels. Use the / symbol to separate levels. For example, "Clothing/Men's clothing/T-shirts"
`coupon`	string	A promo code associated with the item. For example, "PARTNER_SITE_15"
`position`	Integer	Position of item in the list. For example, 2
`price`	Number	Price of a product unit
`quantity`	Integer	Quantity of product units
`variant`	string	A variation of the item. For example, "Red"

Object field
Field	Type	Description
`id` *	string	Item ID. For example, the SKU. You must specify either "name" or "id"
`name` *	string	Name of the product. For example, "T-shirt" You must specify either "name" or "id"
`brand`	string	The brand or trademark associated with the item. For example, "Yandex"
`category`	string	The category the item belongs to. The hierarchy of categories supports up to 5 nesting levels. Use the / symbol to separate levels. For example, "Clothing/Men's clothing/T-shirts"
`coupon`	string	A promo code associated with the item. For example, "PARTNER_SITE_15"
`position`	Integer	Position of item in the list. For example, 2
`price`	Number	Price of a product unit
`quantity`	Integer	Quantity of product units
`variant`	string	A variation of the item. For example, "Red"

Action data

An object containing data about an action performed with an item or set of products.

Processed only if the action is a purchase (<actionType> — purchase).

The structure of the object describing the action is denoted as <actionField>.

When transmitting data about an action, Yandex Metrica creates a goal. This allows you to get information about revenue from Yandex Direct ad campaigns. In the list of available goals in Yandex Direct, this goal is shown as “eCommerce: Purchase (tag № <tag ID>)”. You can track goal completion yourself by transmitting the goal_id field.

Object field
Field	Type	Description
`id` *	string	ID of the product purchased. Required information. Example: TRX#54321
`coupon`	string	A promo code associated with the entire purchase
`goal_id`	Integer	The goal number. Specified if this action was the goal. The goal must be set as a JavaScript event type. To see the goal number, go to Settings (the Goals tab) in the Yandex Metrica interface.
`revenue`	Number	The revenue received. If omitted, it is calculated automatically as the sum of the prices of all the items associated with the purchase

Object field
Field	Type	Description
`id` *	string	ID of the product purchased. Required information. Example: TRX#54321
`coupon`	string	A promo code associated with the entire purchase
`goal_id`	Integer	The goal number. Specified if this action was the goal. The goal must be set as a JavaScript event type. To see the goal number, go to Settings (the Goals tab) in the Yandex Metrica interface.
`revenue`	Number	The revenue received. If omitted, it is calculated automatically as the sum of the prices of all the items associated with the purchase

Examples

To transmit information, you need to create a script on the site that will be responsible for a certain event (for example, making an order) in the format described above. Below are examples of scripts for actions supported by Yandex Metrica.

All the examples assume that the tag was initialized with E-commerce enabled, and data is transferred via the window.dataLayer container.

Viewing a product

The data must be sent the moment the page opens with the product card.

dataLayer.push({
    "ecommerce": {
        "currencyCode": "RUB",
        "detail": {
            "products": [
                {
                    "id": "P15432",
                    "name" : "T-shirt",
                    "price": 477.60,
                    "brand": "Yandex / Яndex",
                    "category": "Clothing/Men's clothing/T-shirts",
                    "variant" : "Red"
                }
            ]
        }
    }
});

Adding an item to the basket

The data must be sent at the moment when the order is added to the basket. For example, upon clicking “Add to basket”.

dataLayer.push({
    "ecommerce": {
        "currencyCode": "RUB",    
        "add": {
            "products": [
                {
                    "id": "43521",
                    "name": "Yandex bag",
                    "price": 654.32,
                    "brand": "Yandex / Яndex",
                    "category": "Accessories/Bags",
                    "quantity": 1
                }
            ]
        }
    }
});

Removing an item from the basket

The data must be sent at the moment when the item is removed from the basket.

dataLayer.push({
    "ecommerce": {
        "currencyCode": "RUB",
        "remove": {
            "products": [
                {
                    "id": "15243",
                    "name": "Set of phone screen wipes - Yandex",
                    "category": "Mobile phone accessories",
                    "quantity": 1
                }
            ]
        }
    }
});

Purchase

The data must be sent the moment the order is confirmed.

dataLayer.push({
    "ecommerce": {
        "currencyCode": "RUB",
        "purchase": {
            "actionField": {
                "id" : "TRX987"
            },
            "products": [
                {
                    "id": "25341",
                    "name": "Yandex men's hoodie",
                    "price": 1345.26,
                    "brand": "Yandex / Яndex",
                    "category": "Clothing/Men's clothing/Sweatshirts and hoodies",
                    "variant": "Orange",
                    "quantity": 1
                },
                {
                    "id": "25314",
                    "name": "Yandex women's hoodie",
                    "price": 1543.62,
                    "brand": "Yandex / Яndex",
                    "category": "Clothing/Women's clothing/Hoodies and sweatshirts",
                    "variant": "White",
                    "quantity": 3
                }
            ]
        }
    }
});

Enabling manually

Checking e-commerce settings

Useful links

Contents

About the data container and its transmission to Yandex Metrica Examples

Enabling manually

Checking e-commerce settings