Skip to main content

Event Object

Overview​

The event object contains detailed information about events used in e-commerce and analytics systems, enabling comprehensive event tracking, analytics, and performance measurement. This object is used as the core structure for all tracked events such as product interactions, user actions, transactions, and custom business events.

Each event object represents a single user action or system occurrence with its associated metadata, value information, identification details, and custom properties that enable precise tracking and analytics capabilities.

Core Structure​

The event object consists of several logical groups of properties:

  • Core Properties - Essential event identification and value tracking
  • Currency & Exchange - Multi-currency support and exchange rate handling
  • Event Identification - Unique IDs for deduplication and transaction tracking
  • Custom Properties - Flexible attributes for business-specific data

Complete Reference​

event object

name string required

info

Name of the event to be sent.

name: "event_name"

value number required

info

Event value in decimal format. Represent the final total order amount, including all costs and discounts.

value: 123.99

currency string required

info

Currency code that specifies the currency in which all monetary values from any object associated with this event are expressed.

Note: This value can be overridden in nested objects if they contain their own value key with a currency specified.

currency: "USD"

exchange_rate number

info

Custom exchange rate for multi-currency. Default has value 1.

Note: This value can be overridden in nested objects if they contain their own value key with a currency specified.

exchange_rate: 1

id string required-if-applicable

info

Event ID — required for transactions or any actions that require deduplication or uniqueness. Represents the unique identifier of a transaction, order, or lead. This can be the unique order, transaction, or action ID used in your system.

id: "UNIQUE_TRANSACTION_123"

properties object recommended

info

Custom Event Properties Examples

properties: {
  cancel_reason: "returning",
}

Implementation Examples​

{
  // Core Properties (Required)
  name: "checkout_completed",
  value: 299.99,
  currency: "USD",
  exchange_rate: 1,
  id: "ORDER_2024_001234",
  
  // Custom Properties
  properties: {
    payment_method: "credit_card",
    shipping_method: "express",
    coupon_code: "SUMMER10",
    customer_type: "returning",
    order_source: "website",
    device_type: "mobile",
    checkout_duration: 180,
    items_count: 3,
    categories: ["electronics", "accessories"],
    first_purchase: false
  }
}

Event Types​

The name field categorizes events for different tracking purposes:

E-commerce events track product and shopping interactions:

{
  name: "product_viewed",        // Product page view
  name: "product_added_to_cart", // Add to cart action
  name: "checkout_started",      // Checkout initiation
  name: "checkout_completed",    // Purchase completion
  name: "product_added_to_wishlist" // Wishlist addition
}

Currency and Exchange Rates​

Event values support multi-currency tracking with automatic conversion:

// USD Base Currency
{
  name: "checkout_completed",
  value: 299.99,
  currency: "USD",
  exchange_rate: 1
}

// EUR with Exchange Rate
{
  name: "checkout_completed",
  value: 249.99,
  currency: "EUR",
  exchange_rate: 1.08 // EUR to USD conversion
}

// Local Currency with Custom Rate
{
  name: "checkout_completed",
  value: 1299.99,
  currency: "RON",
  exchange_rate: 0.22 // RON to USD conversion
}

Custom Properties Strategy​

Event properties enable flexible, business-specific data collection:

properties: {
  // Order Information
  order_type: "standard",
  fulfillment_method: "shipping",
  gift_purchase: true,
  
  // Customer Segmentation
  customer_segment: "vip",
  loyalty_tier: "gold",
  customer_lifetime_orders: 15,
  
  // Marketing Attribution
  utm_source: "facebook",
  utm_medium: "social",
  utm_campaign: "summer_sale",
  
  // Performance Metrics
  page_load_time: 1.2,
  checkout_steps_completed: 4,
  cart_abandonment_recovered: true
}

Value Calculation Guidelines​

The value field should reflect the monetary impact of each event:

E-commerce Events​

  • checkout_completed: Total order value including taxes and shipping
  • product_added_to_cart: Total value of products added
  • product_viewed: Product price or estimated value
  • cart_viewed: Total cart value at time of viewing

Lead Events​

  • lead_created: Estimated lead value or average deal size
  • lead_closed: Actual revenue generated from conversion
  • sign_up: Customer lifetime value estimate
  • lead_disqualified: Potential lost value (often 0)

Content Events​

  • page_viewed: Estimated page value or 0 for informational
  • video_played: Content engagement value
  • document_downloaded: Lead generation value
  • subscription_started: Subscription value or monthly recurring revenue

Usage in Tracking Systems​

The event object is used across all tracking implementations:

Best Practices​

Data Quality​

  • Consistent Naming - Use standardized event names across all implementations
  • Accurate Values - Ensure monetary values reflect true business impact
  • Complete Properties - Include relevant custom properties for segmentation
  • Unique IDs - Use proper unique identifiers for deduplication

Performance Optimization​

  • Essential Data First - Prioritize required fields for fast implementation
  • Relevant Properties - Include only properties that enable actionable insights
  • Consistent Schema - Maintain property naming conventions across events
  • Value Accuracy - Validate monetary values and currency codes

Privacy and Compliance​

  • Data Minimization - Collect only necessary event data
  • Consent Management - Respect user privacy preferences
  • Anonymization - Consider privacy-safe data collection methods
  • Audit Trail - Maintain event tracking for compliance reporting