Skip to main content

Product Object

Overview​

The product object represents a single product or product variant in an e-commerce event. It captures identification, pricing, inventory, categorization, and custom properties for tracking and audience segmentation.

Required fields are id, name, price, price_base, tax_included, tax_percent, and quantity. Fields like parent_id, parent_name, and parent_sku default to their non-parent counterparts if not provided. tax_included defaults to true, quantity defaults to 1, stock_status defaults to true, and tax_percent defaults to the site's configured rate if not provided.

Complete Reference​

products[0] object

id string required

info

Unique product identifier in your system.

id: "PRODUCT_ID"

parent_id string recommended

info

Parent product ID for variants or child products. Defaults to id if not provided.

parent_id: "PRODUCT_PARENT_ID"

name string required

info

Product name or title displayed to users.

name: "Professional Wireless Headphones"

parent_name string

info

Parent product name for variants or child products. Defaults to name if not provided.

parent_name: "Professional Headphones Collection"

price_base number required

info

Original or base price before discounts. Always equal to or greater than price.

price_base: 299.99

price number required

info

Current selling price after discounts. Always equal to or less than price_base.

price: 249.99

tax_included boolean required

info

Whether the price includes taxes. Defaults to true if not provided.

tax_included: true

tax_percent number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

tax_percent: 19

quantity number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

quantity: 2

category string recommended

info

Main product category name

category: "Electronics"

sku string

info

Product SKU (Stock Keeping Unit) for inventory tracking

sku: "SKU_HEADPHONES_PRO"

parent_sku string

info

Parent product SKU for variants or child products. Defaults to sku if not provided.

parent_sku: "SKU_HEADPHONES"

gtin string

info

Global Trade Item Number for product identification

gtin: "1234567890123"

mpn string

info

Manufacturer Part Number assigned by the manufacturer

mpn: "HP-PRO-2024"

ean string

info

European Article Number for product barcoding

ean: "1234567890123"

brand string

info

Product brand or manufacturer name

brand: "AudioTech"

type string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

type: "simple"

stock_status boolean recommended

info

Product availability (true = in stock, false = out of stock). Defaults to true if not provided.

stock_status: true

stock_location string

info

Physical location or warehouse where product is stored

stock_location: "Main Warehouse EU"

created_at number

info

Timestamp when product was added to inventory (milliseconds)

created_at: 1748505040077

url string

info

Direct URL to the product page

url: "https://shop.example.com/products/headphones-pro"

parent_url string

info

URL to the parent product page (for variants)

parent_url: "https://shop.example.com/products/headphones-collection"

image string

info

Main product image URL

image: "https://cdn.example.com/headphones-main.jpg"

images array

info

Array of additional product image URLs

images: [
  "https://cdn.example.com/headphones-front.jpg",
  "https://cdn.example.com/headphones-side.jpg"
]

categories array

info

Array of category objects with name and id properties

  • name (string, required) - Category name
  • id (string) - Category identifier
categories: [
  { name: "Electronics", id: "cat_electronics" },
  { name: "Audio", id: "cat_audio" }
]

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_percent number recommended

info

Tax percentage for the coupon

tax_percent: 21

id string

info

Coupon internal identifier.

id: "COUPON_INTERNAL_ID"

type string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST_ORDER", "SHIPPING").

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. Free-form key-value object. Use properties that match your product catalog and business needs.

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

Examples​

{
  "id": "HEADPHONES_PRO_001",
  "parent_id": "HEADPHONES_PRO_SERIES",
  "name": "Professional Wireless Headphones",
  "parent_name": "Professional Headphones Collection",
  "price_base": 299.99,
  "price": 249.99,
  "tax_included": true,
  "tax_percent": 19,
  "quantity": 1,
  "category": "Electronics",
  "sku": "SKU_HP_PRO_001",
  "parent_sku": "SKU_HP_PRO",
  "gtin": "1234567890123",
  "mpn": "HP-PRO-2024",
  "ean": "1234567890123",
  "brand": "AudioTech",
  "type": "simple",
  "stock_status": true,
  "stock_location": "Main Warehouse EU",
  "created_at": 1748505040077,
  "url": "https://shop.example.com/headphones-pro",
  "parent_url": "https://shop.example.com/headphones-collection",
  "image": "https://cdn.example.com/headphones-main.jpg",
  "images": [
    "https://cdn.example.com/headphones-front.jpg",
    "https://cdn.example.com/headphones-side.jpg"
  ],
  "categories": [
    { "name": "Electronics", "id": "cat_electronics" },
    { "name": "Audio", "id": "cat_audio" },
    { "name": "Headphones", "id": "cat_headphones" }
  ],
  "coupons": [
    {
      "name": "EARLY_BIRD",
      "value": 50.00,
      "tax_included": true,
      "tax_percent": 19,
      "type": "AUTOMATED"
    }
  ],
  "properties": {
    "color": "midnight_black",
    "connectivity": ["bluetooth", "wired"],
    "noise_cancellation": "active",
    "battery_life": "30_hours"
  }
}

Price Logic​

  • price_base is always equal to or greater than price. If price_base is not provided, it defaults to price.
  • If price > price_base, the values are automatically corrected so that price_base becomes the higher value and price the lower.
  • Negative prices are set to 0.

Parent Fields​

For variable products (variants), parent fields provide the connection to the main product:

  • parent_id — defaults to id if not provided
  • parent_name — defaults to name if not provided
  • parent_sku — defaults to sku if not provided
  • parent_url — not defaulted, omitted if empty

Best Practices​

  • Consistent IDs — use the same product IDs across all events for accurate tracking
  • Accurate pricing — ensure price_base and price reflect actual values; the system corrects inverted prices automatically
  • Custom properties — use properties that enable meaningful audience segmentation (color, size, material, etc.); keep naming consistent across products
  • Categories — provide hierarchical categories from broad to specific for better analytics
  • Currency — only specify currency and exchange_rate when the product currency differs from the event currency
  • Product-level coupons — use the coupons array for discounts applied to specific products; use the top-level coupons array for order-wide discounts