Version: 1.1.1

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({
  "ecommerce": null
});
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`	`required`	`"purchase"`	The name of the event indicating a purchase has occurred.
event	`string`	`const: "purchase"`	`"purchase"`	The name of the event indicating a purchase has occurred.
{}ecommerce	`object`			Ecommerce related data for the purchase event.
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.
[]items	`array`	`minItems: 1`		The products purchased in the transaction.
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://tracking-docs-demo.buchert.digital/schemas/1.1.1/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"
      ]
    }
  }
}