items array structure

Almost every ecommerce event contains an items array describing the products involved. Here's the canonical structure for each item in any Biosphere event.

Reference shape

{
  // ─── Required (at least one) ───
  item_id: 'BIO-CRM-001',          // SKU — MUST match Meta Catalog
  item_name: 'Hydrating Day Cream',

  // ─── Strongly recommended ───
  price: 42.00,                    // Number, unit price in units
  quantity: 2,                     // Number, integer
  currency: 'EUR',                 // At item level OR event level

  // ─── Categorization ───
  item_brand: 'Biosphere',
  item_category: 'Skincare',       // level 1
  item_category2: 'Face',          // level 2
  item_category3: 'Hydration',     // up to item_category5

  // ─── Variants ───
  item_variant: '50 ml',           // size, scent, color…

  // ─── Lists (for view_item_list / select_item) ───
  item_list_id: 'plp_face',
  item_list_name: 'PLP Face',
  index: 3,                        // position in the list

  // ─── Discounts ───
  discount: 5.00,                  // unit discount in €
  coupon: 'SPRING10',              // coupon applied to this item

  // ─── Affiliation ───
  affiliation: 'Biosphere Online Store'
}

Field by field

item_id required*

Product SKU. Must be identical across:

• dataLayer (this spec)
• Meta Product Catalog
• Google Merchant Center

* At least item_id or item_name required; ideally both.

item_name recommended

Commercial name. Important for readable GA4 reports.

price required

Unit price after item-level discounts. In units (42.00, not 4200), as a number (not string).

quantity required

Integer. Quantity of this item in this event. For view_item it's 1. For add_to_cart with 2 units added, it's 2.

item_brand recommended

Brand. For Biosphere, usually "Biosphere" (unless reselling third-party brands).

item_category through item_category5 recommended

Category hierarchy, up to 5 levels. Powers GA4 filters and Meta audiences.

item_category: 'Skincare',
item_category2: 'Face',
item_category3: 'Hydration',
item_category4: 'Cream',
item_category5: 'Day'

item_variant optional

Variant discriminator (size, scent, color). Free string.

item_list_id / item_list_name optional

Identifies the list this item was seen/clicked from. Required on view_item_list and select_item.

Context	item_list_id	item_list_name
Category page	plp_<slug>	PLP <Category>
Search results	search_results	Search: <query>
Cross-sell recs	xsell_<context>	Cross-sell <Context>
Homepage carousel	home_carousel	Home Carousel

index optional

Position of the item in the list. Pick 0-based OR 1-based and stay consistent across the site.

discount optional

Unit-level discount, absolute value (not percent). Item originally 50€ now 42€ → price: 42.00, discount: 8.00.

coupon optional

Promo code applied to this item specifically (when different from the order-level coupon).

Summary

Field	Type	Level	Notes
item_id	string	item	SKU, matches Meta Catalog
item_name	string	item	Commercial name
price	number	item	Unit, after discount
quantity	number	item	Integer
currency	string	item or event	ISO 4217
item_brand	string	item
item_category to item_category5	string	item	Hierarchy
item_variant	string	item	Size/color/etc.
item_list_id	string	item or event	Source list
item_list_name	string	item or event
index	number	item	Position
discount	number	item	Unit discount
coupon	string	item or event	Promo code
affiliation	string	item or event

GA4 limits

• Max 200 items per event.
• Max 27 custom parameters per item (beyond the standard set above).
• item_name and item_id: 100 chars max.