Skip to main content

Event Object

Overview​

The event object is the core structure for all tracked events. It captures the event type, monetary value, currency, unique identifier, and custom properties for tracking and analytics.

The name field determines how the event is processed and which destination APIs receive it. The id field is required for events that need deduplication (e.g. checkout_completed, order_canceled). Only events that are mapped in your account configuration will be accepted.

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",
}

Examples​

{
  "name": "checkout_completed",
  "value": 299.99,
  "currency": "USD",
  "exchange_rate": 1,
  "id": "ORDER_2024_001234",
  "properties": {
    "payment_method": "credit_card",
    "shipping_method": "express",
    "items_count": 3
  }
}

Event ID​

The id field serves different purposes depending on the event type:

  • Transaction events (checkout_completed, order_canceled) — id is required and used for deduplication. Events with duplicate IDs are not processed again per destination.
  • Non-transaction events (product_viewed, page_viewed, etc.) — id is optional. If not provided, a unique ID is generated automatically.

Custom Properties​

The properties object allows you to attach any custom key-value data to an event. Use it for business-specific attributes that enable segmentation and analytics in your destinations.

{
  "properties": {
    "payment_method": "credit_card",
    "customer_type": "returning",
    "coupon_code": "SUMMER10",
    "checkout_duration": 180
  }
}

Keep custom properties focused — limit to 5-10 key properties per event for optimal performance across destinations.

Currency and Exchange Rate​

The currency field applies to all monetary values in the event and its nested objects (products, shipping, coupons). Nested objects can override currency and exchange_rate individually when they use a different currency.

{
  "name": "checkout_completed",
  "value": 1299.99,
  "currency": "RON",
  "exchange_rate": 0.22
}

Best Practices​

  • Consistent event names — use the same event names across all implementations for accurate tracking
  • Accurate values — ensure value reflects the actual monetary impact (order total, lead value, etc.)
  • Unique IDs for transactions — always provide a unique id for checkout_completed and order_canceled to prevent duplicate processing
  • Focused properties — include only properties that enable actionable insights in your destinations
  • Currency consistency — use the same currency code across related events when possible