Skip to main content

Product Object

Overview​

The product object contains detailed information about products in e-commerce events, enabling comprehensive product tracking, analytics, and audience segmentation. This object is used within the detail.products array in all e-commerce events such as product views, cart interactions, and purchase completions.

Each product object represents a single product or product variant with its associated metadata, pricing information, inventory details, and custom properties that enable precise tracking and targeting capabilities.

Core Structure​

The product object consists of several logical groups of properties:

  • Core Properties - Essential product identification and pricing
  • Product Supplemental Identification - SKUs, GTINs, and other product codes
  • Product Details - Brand, type, and variant information
  • Inventory & Location - Stock status and warehouse information
  • URLs & Media - Product pages and images
  • Categories - Product categorization and taxonomy
  • Coupons - Product-level discounts and promotions
  • Custom Properties - Flexible attributes for segmentation

Complete Reference​

products[0] object

id string required

info

Unique product identifier in your system.

id: "PRODUCT_ID"

parent_id string required

info

Parent product ID for variants or child products (can be same as id if no parent concept exists).

parent_id: "PRODUCT_PARENT_ID"

name string required

info

Product name or title displayed to users.

name: "PRODUCT_NAME"

parent_name string

info

Parent product name for variants or child products

parent_name: "PRODUCT_PARENT_NAME"

price_base number required

info

Original or base price before discounts (decimal format: 299.99)

price_base: 120.99

price number required

info

Current selling price after discounts (decimal format: 249.99)

price: 100.99

tax_included boolean required

info

Whether the price includes taxes (true/false)

tax_included: true

tax_percent number required

info

Tax percentage applied to the product (0-100)

tax_percent: 21

quantity number required

info

Quantity of this product in the context of the event

quantity: 1

category string required

info

Main product category name

category: "PRODUCT_MAIN_CATEGORY_NAME"

sku string

info

Product SKU (Stock Keeping Unit) for inventory tracking

sku: "PRODUCT_SKU"

parent_sku string

info

Parent product SKU for variants or child products

parent_sku: "PRODUCT_PARENT_SKU"

gtin string

info

Global Trade Item Number for product identification

gtin: "PRODUCT_GTIN"

mpn string

info

Manufacturer Part Number assigned by the manufacturer

mpn: "PRODUCT_MPN"

ean string

info

European Article Number for product barcoding

ean: "PRODUCT_EAN"

brand string

info

Product brand or manufacturer name

brand: "PRODUCT_BRAND"

type string

info

Product type: "simple", "variable", "virtual", "bundle", "subscription", "external".

Default: simple.

type: "simple"

stock_status boolean recommended

info

Product availability status (true = in stock, false = out of stock)

stock_status: true

stock_location string

info

Physical location or warehouse where product is stored

stock_location: "WAREHOUSE_NAME"

created_at string recommended

info

Timestamp when product was added to inventory (milliseconds)

created_at: 1754926521690

url string

info

Direct URL to the product page

url: "https://shop.example.com/products/laptop-page"

parent_url string

info

URL to the parent product page (for variants)

parent_url: "https://shop.example.com/products/laptop-page"

image string

info

Main product image URL

image: "https://cdn.example.com/products/laptop-image.jpg"

images array

info

Array of additional product image URLs

images: [
  "https://cdn.example.com/products/laptop-image-1.jpg",
  "https://cdn.example.com/products/laptop-image-2.jpg",
]

categories array

info

Array of category objects with name and id properties

  • name (string, required) - Category name
  • id (string) - Category identifier
categories: [
  {
    name: "PRODUCT_FIRST_CATEGORY_NAME",
    id: "1111"
  },
  {
    name: "PRODUCT_SECOND_CATEGORY_NAME",
    id: "1111"
  }
]

coupons array

info

Array of product-level coupons applied to this product. View complete Coupon Object documentation

coupons[0] (object) - required

name string required

info

Coupon name or code.

name: "FREE SHIPPING"

value number recommended

info

Coupon discount value.

value: 123.99

tax_included boolean recommended

info

Whether coupon value includes taxes

tax_included: true

tax_precent string recommended

info

Tax percentage for the coupon

tax_precent: 21

id string

info

Coupon internal identifier.

id: "COUPON_INTERNAL_ID"

type string

info

Coupon type (e.g., "LOYALTY", "SEASONAL", "FIRST_ORDER")

type: "SHIPPING"

currency string required-if-applicable

info

Currency code. Specifies the currency code when it differs from event.currency.

currency: "USD"

exchange_rate number

info

Custom exchange rate for multi-currency. Default has value 1. Specifies when it differs from event.exchange_rate.

exchange_rate: 1

properties object recommended

info

Custom product attributes for audience segmentation. Use custom properties that match your product catalog and business needs.

  • color (string|array) - Product color(s): "blue" or ["blue", "navy"]
  • size (string) - Product size: "S", "M", "L", "XL"
  • material (string|array) - Product material(s): "cotton" or ["cotton", "polyester"]
  • connectivity (string|array) - Connection types: "wireless" or ["wifi", "bluetooth"]
  • storage (string) - Storage capacity: "256GB", "512GB"
  • dimensions (string) - Physical dimensions: "120x60x75cm"
Product Segmentation

Use the properties object to store custom product attributes, with property names defined by each business as needed, that enable advanced segmentation, personalization, and analytics across your marketing campaigns.

properties: {
  color: "space_gray",
  storage: "256GB", 
  memory: "16GB",
  connectivity: ["wifi", "bluetooth"],
  warranty: "2_years",
  energy_rating: "A++",
  brand_series: "pro_line"
  }

currency string required-if-applicable

info

Currency code. Specifies the currency code when it differs from event.currency.

currency: "USD"

exchange_rate number

info

Custom exchange rate for multi-currency. Default has value 1. Specifies when it differs from event.exchange_rate.

exchange_rate: 1

Implementation Examples​

{
  // Core Properties (Required)
  id: "PRODUCT_001",
  parent_id: "PRODUCT_001",
  name: "Professional Wireless Headphones",
  price_base: 299.99,
  price: 249.99,
  tax_included: true,
  tax_percent: 19,
  quantity: 2,
  category: "Electronics",
  
  // Product Identification
  sku: "SKU_HEADPHONES_PRO",
  gtin: "1234567890123",
  mpn: "HP-PRO-2024",
  ean: "1234567890123",
  
  // Product Details
  brand: "AudioTech",
  type: "simple",
  parent_sku: "SKU_HEADPHONES_PRO",
  parent_name: "Professional Wireless Headphones",
  
  // Inventory & Location
  stock_status: true,
  stock_location: "Main Warehouse EU",
  created_at: 1748505040077,
  
  // URLs & Media
  url: "https://www.example.com/headphones-pro",
  parent_url: "https://www.example.com/headphones-pro",
  image: "https://cdn.example.com/headphones-main.jpg",
  images: [
    "https://cdn.example.com/headphones-front.jpg",
    "https://cdn.example.com/headphones-side.jpg",
    "https://cdn.example.com/headphones-back.jpg"
  ],
  
  // Categories
  categories: [
    {
      name: "Electronics",
      id: "cat_electronics"
    },
    {
      name: "Audio",
      id: "cat_audio"
    },
    {
      name: "Headphones",
      id: "cat_headphones"
    }
  ],
  
  // Product-level Coupons
  coupons: [
    {
      name: "EARLY_BIRD",
      value: 50.00,
      tax_percent: 19,
      tax_included: true,
      type: "AUTOMATED"
    }
  ],
  
  // Custom Properties
  properties: {
    color: "midnight_black",
    connectivity: ["bluetooth", "wired"],
    noise_cancellation: "active",
    battery_life: "30_hours",
    driver_size: "40mm",
    frequency_response: "20Hz-20kHz",
    warranty: "2_years",
    weight: "280g"
  }
}

Product Types​

The type field categorizes products for different handling:

Simple products are standalone items without variations:

{
  id: "SIMPLE_001",
  type: "simple",
  name: "Wireless Mouse",
  // Single product, no variants
}

Categories Structure​

Product categorization supports multiple hierarchical levels:

categories: [
  {
    name: "Electronics",      // Top level
    id: "cat_electronics"
  },
  {
    name: "Audio Equipment",   // Second level
    id: "cat_audio"
  },
  {
    name: "Headphones",       // Third level
    id: "cat_headphones"
  },
  {
    name: "Wireless",         // Fourth level
    id: "cat_wireless"
  }
]

Coupons & Discounts​

Product-level coupons track discounts applied to individual products:

coupons: [
  {
    name: "PRODUCT_DISCOUNT_10",
    value: 25.00,
    tax_percent: 19,
    tax_included: true,
    type: "AUTOMATED"
  },
  {
    name: "BULK_PURCHASE",
    value: 15.00,
    tax_percent: 19,
    tax_included: true,
    type: "MANUAL"
  }
]

Usage in E-commerce Events​

The product object is used in all e-commerce events within the detail.products array:

Best Practices​

Data Quality​

  • Consistent IDs - Use the same product IDs across all events
  • Complete Information - Include as many optional fields as available
  • Accurate Pricing - Ensure price_base and price reflect actual values
  • Current Stock Status - Update stock_status based on real inventory

Custom Properties Strategy​

  • Standardized Naming - Use consistent property names across products
  • Relevant Attributes - Include properties that enable meaningful segmentation
  • Array vs String - Use arrays for multi-value properties (colors, materials)
  • Advertising Compatibility - Consider platform requirements for dynamic ads

Performance Optimization​

  • Essential Data First - Prioritize required fields for fast implementation
  • Incremental Enhancement - Add optional fields as data becomes available
  • Image Optimization - Use CDN URLs for product images
  • Caching Strategy - Cache product data to reduce API calls during events