Purchase Event

A purchase event fires when a user completes a purchase. Based on Google Analytics 4 ecommerce event specifications.

DataLayer Example

window.dataLayer.push({
  "event": "purchase",
  "ecommerce": {
    "transaction_id": "T_12345",
    "value": 72.05,
    "currency": "USD",
    "coupon": "SUMMER_SALE",
    "shipping": 5.99,
    "tax": 3.6,
    "customer_type": "new",
    "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: "purchase" The name of the event indicating a purchase has occurred.

ecommerce⤵ object Ecommerce related data for the purchase event.

ecommerce { }

Property Type Constraints Examples Description

transaction_id string required T_12345, TXN_20231205_001 The unique ID of a transaction. The transaction_id parameter helps avoid duplicate transaction recording.

value number required 72.05, 99.99, 150.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.

minLength: 3

maxLength: 3

coupon string SUMMER_SALE, WELCOME15 The coupon/code associated with the event. Event-level and item-level coupon parameters are independent.

shipping number 5.99, 10, 0 The shipping cost associated with the transaction.

tax number 3.6, 7.5, 0 The tax associated with the transaction.

customer_type string enum: [new, returning] new, returning Whether this is from a new or returning customer. 'new' = customer with no purchase in the specified time window (default 540 days). 'returning' = customer with purchase in the specified time window.

items⤵ array required The products purchased in the transaction.

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/purchase-event.json",
  "title": "Purchase Event",
  "description": "A purchase event fires when a user completes a purchase. Based on Google Analytics 4 ecommerce event specifications.",
  "type": "object",
  "allOf": [
    {
      "$ref": "./components/dataLayer.json"
    }
  ],
  "properties": {
    "event": {
      "type": "string",
      "const": "purchase",
      "description": "The name of the event indicating a purchase has occurred."
    },
    "ecommerce": {
      "type": "object",
      "description": "Ecommerce related data for the purchase event.",
      "properties": {
        "transaction_id": {
          "type": "string",
          "description": "The unique ID of a transaction. The transaction_id parameter helps avoid duplicate transaction recording.",
          "examples": [
            "T_12345",
            "TXN_20231205_001"
          ]
        },
        "value": {
          "type": "number",
          "description": "The monetary value of the event. Set value to the sum of (price * quantity) for all items in items.",
          "examples": [
            72.05,
            99.99,
            150.5
          ]
        },
        "currency": {
          "type": "string",
          "description": "The currency of the items in ISO 4217 three-letter format. Required when value is set.",
          "minLength": 3,
          "maxLength": 3,
          "examples": [
            "USD",
            "EUR",
            "GBP"
          ]
        },
        "coupon": {
          "type": "string",
          "description": "The coupon/code associated with the event. Event-level and item-level coupon parameters are independent.",
          "examples": [
            "SUMMER_SALE",
            "WELCOME15"
          ]
        },
        "shipping": {
          "type": "number",
          "description": "The shipping cost associated with the transaction.",
          "examples": [
            5.99,
            10,
            0
          ]
        },
        "tax": {
          "type": "number",
          "description": "The tax associated with the transaction.",
          "examples": [
            3.6,
            7.5,
            0
          ]
        },
        "customer_type": {
          "type": "string",
          "enum": [
            "new",
            "returning"
          ],
          "description": "Whether this is from a new or returning customer. 'new' = customer with no purchase in the specified time window (default 540 days). 'returning' = customer with purchase in the specified time window.",
          "examples": [
            "new",
            "returning"
          ]
        },
        "items": {
          "type": "array",
          "description": "The products purchased in the transaction.",
          "minItems": 1,
          "items": {
            "$ref": "./components/product.json"
          }
        }
      },
      "required": [
        "transaction_id",
        "value",
        "currency",
        "items"
      ]
    }
  }
}