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: "ord_abc123"

reason string

info

Short human-readable reason associated with a lifecycle event — the cancellation reason for order_canceled, or the disqualification reason for lead_disqualified. Free-form string; keep it short and consistent across your implementations so it can be grouped for reporting.

reason: "out_of_stock"

properties object recommended

info

Custom Event Properties Examples

properties: {
  fulfillment_method: "delivery",
  gift_wrap: "true"
}

Examples​

{
  "name": "checkout_completed",
  "value": 299.99,
  "currency": "USD",
  "exchange_rate": 1,
  "id": "ord_abc123",
  "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.

Event Value​

The value field is the monetary impact of the event. For most events it is simply the amount involved (lead value, product price, etc.), but two events have a strict, canonical composition the framework depends on:

Canonical rule — event.value for checkout_completed and order_canceled
  • checkout_completed — value MUST always equal products + shipping + any other costs − order-level coupons, with tax INCLUDED.
  • order_canceled — value MUST always equal only the value of the returned/canceled products, with tax INCLUDED — no shipping, no other costs.

These compositions are a hard contract. The framework uses them to correctly derive tax-excluded and shipping-excluded values per destination (GA4 value overrides, Google Ads conversion values, refund adjustments). Sending anything else (net values, totals with shipping on refunds, tax-excluded amounts) produces wrong destination values — fix the integration, never expect the framework to compensate.

Event Reason​

The optional reason field is a short, human-readable string that captures the why behind a lifecycle event. Prefer it over a custom property so the value lands in a predictable, queryable place across destinations.

Common values:

  • order_canceled → "customer_request", "out_of_stock", "payment_declined"
  • lead_disqualified → "out_of_icp", "no_budget", "no_authority", "duplicate"

Keep the value short (snake_case recommended) and consistent across implementations so it can be grouped for reporting.

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": "EXAMPLE_COUPON",
    "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": "USD",
  "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.); for checkout_completed and order_canceled follow the canonical composition in Event Value
  • 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