Add to Cart Event

An add_to_cart event fires when a user adds one or more items to their shopping cart. Based on Google Analytics 4 ecommerce event specifications.

DataLayer Example

window.dataLayer.push({
  "event": "add_to_cart",
  "ecommerce": {
    "value": 30.03,
    "currency": "USD",
    "items": [
      {
        "item_id": "SKU_12345",
        "item_name": "Stan and Friends Tee",
        "affiliation": "Google Merchandise Store",
        "coupon": "SUMMER_FUN",
        "discount": 2.22,
        "index": 0,
        "item_brand": "Google",
        "item_category": "Apparel",
        "item_category2": "Adult",
        "item_category3": "Shirts",
        "item_category4": "Crew",
        "item_category5": "Short sleeve",
        "item_list_id": "related_products",
        "item_list_name": "Related Products",
        "item_variant": "green",
        "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
        "price": 10.01,
        "quantity": 1,
        "promotion_id": "P_12345",
        "promotion_name": "Summer Sale",
        "creative_name": "summer_banner2",
        "creative_slot": "featured_app_1",
        "google_business_vertical": "retail"
      }
    ]
  }
});

Event Properties

Property Type Constraints Examples Description

event string const: "add_to_cart" The name of the event indicating a add_to_cart has occurred.

ecommerce⤵ object Ecommerce related data for the purchase event.

ecommerce { }

Property Type Constraints Examples Description

value number 30.03, 99.99, 45.5 The monetary value of the event. Set value to the sum of (price * quantity) for all items in items.

currency string required USD, EUR, GBP The currency of the items in ISO 4217 three-letter format. Required when value is set.

items⤵ array required The products added to the cart.

minItems: 1

items [ ]

Property	Type	Examples	Description
item_id	`string`	SKU_12345, PROD_98765	The ID of the item. Either item_id or item_name is required.
item_name	`string`	Stan and Friends Tee, Blue Running Shoes	The name of the item. Either item_id or item_name is required.
affiliation	`string`	Google Merchandise Store, Nike Store	A product affiliation to indicate a supplier or store. Note: affiliation is only available at the item level.
coupon	`string`	SUMMER_FUN, WELCOME20, SAVE10	The coupon name/code associated with the item. Coupon parameters at event and item levels are independent.
discount	`number`	2.22, 5, 10.5	The monetary value of the discount per unit applied to the item.
index	`number`	0, 1, 2	The index or position of the item in a list.
item_brand	`string`	Google, Nike, Adidas	The brand of the item.
item_category	`string`	Apparel, Footwear, Electronics	The category of the item. If used as part of a category hierarchy or taxonomy, this is the first category.
item_category2	`string`	Adult, Women, Men	The second category hierarchy or additional taxonomy of the item.
item_category3	`string`	Shirts, Shoes, Boots	The third category hierarchy or additional taxonomy of the item.
item_category4	`string`	Crew, Running, Casual	The fourth category hierarchy or additional taxonomy of the item.
item_category5	`string`	Short sleeve, Long distance, Lightweight	The fifth category hierarchy or additional taxonomy of the item.
item_list_id	`string`	related_products, search_results, recommendations	The ID of the list in which the item was presented to the user. If set, item_list_id at the event level is ignored. If not set, item_list_id at the event level is used if available.
item_list_name	`string`	Related Products, Search Results, Recommended Items	The name of the list in which the item was presented to the user. If set, item_list_name at the event level is ignored. If not set, item_list_name at the event level is used if available.
item_variant	`string`	green, Blue Size 10, M-Black	The item variant or unique code or description for additional item details/options.
location_id	`string`	ChIJIQBpAG2ahYAR_6128GcTUEo, store_123, location_sf	The physical location associated with the item, such as the location of a brick-and-mortar store. It is recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. Note: location_id is only available at the item level.
price	`number`	10.01, 21.01, 89.99	The price of the item in the specified currency unit. If a discount is applied to the item, set price to the reduced per-unit price and provide the per-unit price discount in the discount parameter.
quantity	`number`	1, 2, 3	The item quantity. If not set, quantity is set to 1.
promotion_id	`string`	P_12345, PROMO_001	The ID of the promotion associated with the item.
promotion_name	`string`	Summer Sale, Black Friday, Flash Deal	The name of the promotion associated with the item.
creative_name	`string`	summer_banner2, holiday_email_v1	The name of the promotion creative.
creative_slot	`string`	featured_app_1, top_banner, sidebar	The name of the creative slot associated with the item.
google_business_vertical	`string`	retail, ecommerce	The business vertical for the item (e.g., 'retail').

View Raw JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/add-to-cart-event.json",
  "title": "Add to Cart Event",
  "description": "An add_to_cart event fires when a user adds one or more items to their shopping cart. Based on Google Analytics 4 ecommerce event specifications.",
  "type": "object",
  "allOf": [
    {
      "$ref": "./components/dataLayer.json"
    }
  ],
  "properties": {
    "event": {
      "type": "string",
      "const": "add_to_cart",
      "description": "The name of the event indicating a add_to_cart has occurred."
    },
    "ecommerce": {
      "type": "object",
      "description": "Ecommerce related data for the purchase event.",
      "properties": {
        "value": {
          "type": "number",
          "description": "The monetary value of the event. Set value to the sum of (price * quantity) for all items in items.",
          "examples": [
            30.03,
            99.99,
            45.5
          ]
        },
        "currency": {
          "type": "string",
          "description": "The currency of the items in ISO 4217 three-letter format. Required when value is set.",
          "examples": [
            "USD",
            "EUR",
            "GBP"
          ]
        },
        "items": {
          "type": "array",
          "description": "The products added to the cart.",
          "minItems": 1,
          "items": {
            "$ref": "./components/product.json"
          }
        }
      },
      "required": [
        "currency",
        "items"
      ]
    }
  }
}