# Items Array Complete Reference

## Items Array Overview

The `items` array is a core component of ecommerce tracking in GA4. It appears in all ecommerce events and contains product-level data.

---

## Array Structure

```javascript
'items': [
  {
    // Required (at least one)
    'item_id': 'SKU_123',
    'item_name': 'Product Name',

    // Highly Recommended
    'price': 99.99,
    'quantity': 1,
    'item_category': 'Electronics',

    // Optional
    'item_brand': 'Brand Name',
    'item_variant': 'Blue/Large',
    'item_category2': 'Phones',
    'item_category3': 'Smartphones',
    'item_category4': 'Android',
    'item_category5': 'Flagship',
    'coupon': 'SUMMER20',
    'discount': 10.00,
    'affiliation': 'Online Store',
    'item_list_id': 'new_arrivals',
    'item_list_name': 'New Arrivals',
    'location_id': 'store_123',
    'index': 0
  }
]
```

---

## Field Details

### item_id (REQUIRED - at least one)

**Purpose:** Unique product identifier

**Format:** String (any format)

**Examples:**
- `SKU_12345`
- `PROD_ABC123`
- `isbn_9781234567890`
- `gtin_1234567890123`

**Best Practices:**
- Use consistent format across all events
- Match your internal product database ID
- Never include user-specific data

```javascript
'item_id': 'SKU_BLUE_TSHIRT_LARGE'
```

---

### item_name (REQUIRED - at least one)

**Purpose:** Product display name

**Format:** String (max 100 characters recommended)

**Examples:**
- `Blue T-Shirt`
- `Premium Wireless Headphones - Black`
- `Winter Jacket - Size M`

**Best Practices:**
- Use human-readable name
- Include variant information if not separate
- Consistent across ecommerce platform

```javascript
'item_name': 'Blue T-Shirt - Large'
```

---

### price (HIGHLY RECOMMENDED)

**Purpose:** Individual unit price

**Format:** Number (decimal)

**Important:**
- Per-unit price, NOT total
- Total = price × quantity
- Should match product catalog price

```javascript
'price': 99.99
```

**Multi-Item Example:**
```javascript
'items': [
  {
    'item_id': 'SKU_001',
    'item_name': 'Product A',
    'price': 99.99,
    'quantity': 2  // Total for this item: 199.98
  },
  {
    'item_id': 'SKU_002',
    'item_name': 'Product B',
    'price': 50.00,
    'quantity': 1  // Total for this item: 50.00
  }
  // Grand total: 249.98
]
```

---

### quantity (HIGHLY RECOMMENDED)

**Purpose:** Number of units

**Format:** Integer

**Examples:**
- `1` - Single item
- `2` - Two units
- `10` - Ten units

**Important:**
- Should be ≥ 1
- Impacts value calculations
- Should match cart quantity

```javascript
'quantity': 3
```

**Calculation Example:**
```
price: 99.99
quantity: 3
item_total: 99.99 × 3 = 299.97
```

---

### item_category (HIGHLY RECOMMENDED)

**Purpose:** Primary product category

**Format:** String (e.g., "Electronics", "Apparel", "Home & Garden")

**Best Practices:**
- Use main category only
- Keep consistent across platform
- Use hierarchical category structure

```javascript
'item_category': 'Electronics'
```

**GA4 Reporting:**
- Enables "Items by category" analysis
- Product category segments
- Category-level conversion rates

---

### item_brand (OPTIONAL)

**Purpose:** Brand/manufacturer

**Format:** String

**Examples:**
- `Nike`
- `Sony`
- `Apple`
- `Our Store Brand`

```javascript
'item_brand': 'Nike'
```

**Reporting Use:**
- Brand performance analysis
- Brand-specific conversion rates
- Brand preference trends

---

### item_variant (OPTIONAL)

**Purpose:** Product variant (size, color, style, etc.)

**Format:** String (describe the specific variant)

**Examples:**
- `Blue/Large`
- `Red/Medium/Cotton`
- `Gold/64GB`
- `Leather/Black/Premium`

**Best Practices:**
- Standardize format (Color/Size)
- Separate multiple variants with slash
- Match product catalog variant descriptions

```javascript
'item_variant': 'Blue/Large/Cotton'
```

**Reporting Use:**
- Variant popularity analysis
- Which sizes/colors sell best
- Variant conversion rates

---

### item_category2 through item_category5 (OPTIONAL)

**Purpose:** Hierarchical category levels

**Format:** String

**Examples:**

**Level Structure:**
```
item_category:  'Electronics'     (Main category)
item_category2: 'Audio'           (Subcategory)
item_category3: 'Headphones'      (Sub-subcategory)
item_category4: 'Wireless'        (Further specification)
item_category5: 'Premium'         (Additional tier)
```

**Full Example:**
```javascript
'item_id': 'SKU_HEADPHONE_001',
'item_name': 'Premium Wireless Headphones',
'item_category': 'Electronics',
'item_category2': 'Audio',
'item_category3': 'Headphones',
'item_category4': 'Wireless',
'item_category5': 'Over-Ear'
```

**Another Example:**
```javascript
'item_category': 'Apparel',
'item_category2': 'Mens',
'item_category3': 'Shirts',
'item_category4': 'T-Shirts',
'item_category5': 'Short-Sleeve'
```

**Reporting Use:**
- Multi-level category analysis
- Category-to-purchase funnel
- Detailed product segmentation

---

### coupon (OPTIONAL)

**Purpose:** Coupon/promotion code applied to item

**Format:** String (coupon code)

**Examples:**
- `SUMMER20`
- `SAVE10`
- `WELCOME5`
- `NEWYEAR50`

**Important:**
- Item-level coupon (not transaction-level)
- Multiple items can have different coupons
- Usually paired with `discount` field

```javascript
'coupon': 'SUMMER20'
```

**Transaction-Level Example:**
```javascript
gtag('event', 'purchase', {
  'transaction_id': 'TXN_12345',
  'coupon': 'SITEWIDE10',  // Applies to whole purchase
  'items': [
    {
      'item_id': 'SKU_001',
      'coupon': 'PRODUCT15'  // Different coupon on this item
    }
  ]
});
```

---

### discount (OPTIONAL)

**Purpose:** Discount amount on item

**Format:** Number (decimal, discount amount in transaction currency)

**Examples:**
- `10.00` - $10 discount
- `5.50` - $5.50 discount
- `0.99` - 99 cents discount

**Relationship to Price:**
```
original_price: 99.99
discount: 10.00
final_price: 89.99
```

**Implementation:**
```javascript
'price': 99.99,
'discount': 10.00,
// Customer pays: 99.99 - 10.00 = 89.99
```

**Reporting Use:**
- Discount impact analysis
- Discount effectiveness
- Revenue impact of promotions

---

### affiliation (OPTIONAL)

**Purpose:** Vendor/store name for multi-vendor platforms

**Format:** String

**Examples:**
- `Nike Store`
- `Amazon Marketplace`
- `Vendor ABC`
- `Warehouse Location 3`

**Use Cases:**
- Multi-vendor marketplaces
- Multiple physical locations
- Different store names

```javascript
'affiliation': 'Nike Store'
```

**Transaction-Level:**
```javascript
gtag('event', 'purchase', {
  'affiliation': 'Main Online Store',  // Default/transaction-level
  'items': [
    {
      'item_id': 'SKU_001',
      'affiliation': 'Nike Store'  // Override for this item
    }
  ]
});
```

---

### item_list_id (OPTIONAL)

**Purpose:** Identifier for the list/collection item came from

**Format:** String (identifier, not display name)

**Examples:**
- `search_results`
- `category_electronics`
- `homepage_featured`
- `related_products`
- `sale_section`

**Use Cases:**
```javascript
// From search results
gtag('event', 'select_item', {
  'items': [{
    'item_id': 'SKU_123',
    'item_list_id': 'search_results'
  }]
});

// From category
gtag('event', 'view_item', {
  'items': [{
    'item_id': 'SKU_123',
    'item_list_id': 'category_shoes'
  }]
});

// From recommendations
gtag('event', 'select_item', {
  'items': [{
    'item_id': 'SKU_123',
    'item_list_id': 'recommendations_widget'
  }]
});
```

**Reporting Use:**
- Track which collections drive sales
- Compare performance of different lists
- Identify high-converting collections

---

### item_list_name (OPTIONAL)

**Purpose:** Display name for the list/collection

**Format:** String (human-readable)

**Examples:**
- `Search Results for Shoes`
- `Electronics Category`
- `New Arrivals`
- `Customers Also Bought`
- `Summer Sale`

**Important:**
- Use display name (what users see)
- Pair with `item_list_id` for consistency
- Should be understandable in reports

```javascript
'item_list_name': 'New Arrivals'
```

**Full Example:**
```javascript
gtag('event', 'view_item_list', {
  'items': [{...}],
  'item_list_id': 'featured_section',
  'item_list_name': 'Featured Products - Home Page'
});
```

---

### location_id (OPTIONAL)

**Purpose:** Physical store location identifier

**Format:** String (store ID or location code)

**Examples:**
- `store_123`
- `NYC_Broadway`
- `location_LAX_001`
- `warehouse_sf`

**Use Cases:**
- Multi-location retailers
- In-store purchases
- Store-based pickup
- Inventory tracking

```javascript
'location_id': 'store_downtown_la'
```

**E-Commerce + In-Store:**
```javascript
gtag('event', 'purchase', {
  'items': [
    {
      'item_id': 'SKU_001',
      'location_id': 'store_sf'  // Picked up at SF store
    }
  ]
});
```

---

### index (OPTIONAL)

**Purpose:** Position of item in list (0-based)

**Format:** Integer (0, 1, 2, ...)

**Important:**
- 0-based indexing (first item = 0)
- Useful for tracking list position impact
- Typically auto-generated

```javascript
'items': [
  {
    'item_id': 'SKU_001',
    'item_name': 'First Product',
    'index': 0
  },
  {
    'item_id': 'SKU_002',
    'item_name': 'Second Product',
    'index': 1
  },
  {
    'item_id': 'SKU_003',
    'item_name': 'Third Product',
    'index': 2
  }
]
```

**Reporting Use:**
- Position analysis (first item gets more clicks?)
- List effectiveness by position
- A/B test different orderings

---

## Custom Item Parameters

**Advanced:** Register custom item parameters as custom dimensions

**Example Custom Parameters:**
```javascript
'items': [{
  'item_id': 'SKU_001',
  'item_name': 'Product A',

  // Custom parameters (must be registered as custom dimensions)
  'item_color': 'blue',
  'item_material': 'cotton',
  'supplier': 'vendor_123',
  'profit_margin': '45%',
  'in_stock': true
}]
```

**Registration Process:**
1. Send custom parameter in items array
2. Admin → Custom Definitions → Create Custom Dimension
3. Set Scope: "Item"
4. Map to parameter name (e.g., "item_color")
5. Wait 24-48 hours
6. Use in "Items" report

---

## Complete Examples

### Simple Product

```javascript
'items': [{
  'item_id': 'TSHIRT_001',
  'item_name': 'Blue T-Shirt',
  'price': 29.99,
  'quantity': 1,
  'item_category': 'Apparel'
}]
```

### Product with Variants

```javascript
'items': [{
  'item_id': 'PHONE_IPHONE_BLACK_256GB',
  'item_name': 'iPhone 15 Pro - Black - 256GB',
  'item_brand': 'Apple',
  'item_category': 'Electronics',
  'item_category2': 'Phones',
  'item_category3': 'Smartphones',
  'item_variant': 'Black/256GB',
  'price': 999.99,
  'quantity': 1
}]
```

### Multiple Items with Discounts

```javascript
'items': [
  {
    'item_id': 'SKU_001',
    'item_name': 'Product A',
    'price': 99.99,
    'quantity': 2,
    'item_category': 'Electronics',
    'coupon': 'SUMMER20',
    'discount': 20.00
  },
  {
    'item_id': 'SKU_002',
    'item_name': 'Product B',
    'price': 50.00,
    'quantity': 1,
    'item_category': 'Accessories',
    'discount': 5.00
  }
]
```

### Marketplace with Affiliations

```javascript
'items': [
  {
    'item_id': 'VENDOR1_SKU_001',
    'item_name': 'Product from Vendor 1',
    'affiliation': 'Vendor ABC',
    'price': 49.99,
    'quantity': 1
  },
  {
    'item_id': 'VENDOR2_SKU_002',
    'item_name': 'Product from Vendor 2',
    'affiliation': 'Vendor XYZ',
    'price': 29.99,
    'quantity': 1
  }
]
```

---

## Validation Rules

**Requirements:**
- ✅ At least one item in array (minimum 1)
- ✅ Maximum 27 items per event
- ✅ Each item has item_id OR item_name (at least one)
- ✅ price and quantity are numbers (not strings)
- ✅ quantity ≥ 1
- ✅ price > 0 (positive value)

**Common Errors:**
- ❌ Empty items array `[]`
- ❌ Item without ID or name
- ❌ Price as string `"99.99"` (must be number `99.99`)
- ❌ Quantity as string `"2"` (must be number `2`)
- ❌ Negative price or quantity
- ❌ More than 27 items

---

## Testing Items Array

**Use DebugView to verify:**

1. Event contains items array
2. Each item has at least item_id or item_name
3. Prices and quantities are numeric
4. Array structure is valid JSON
5. No special characters in field names

**Debug Checklist:**
```
✓ Items array present
✓ Minimum 1 item
✓ Maximum 27 items
✓ Item ID or name exists
✓ Numeric values (not strings)
✓ Prices match product catalog
✓ Quantities match cart data
✓ Categories consistent with product data
```