Tracking SDK

Event schema

Canonical reference for event types and payload fields across the JavaScript SDK and webhook API.

This is the single source of truth for TrustData's event schema. Both the JavaScript SDK and the webhook API use the same payload format — same field names, same objects, same structure.

Event types

SDK event name	Webhook topic	Description
`purchase`	`purchase`	Completed transaction
`generate_lead`	`lead`	Lead form submission
`sign_up`	`signup`	Account registration
`page_view`	—	Page view (SDK only)
—	`refund`	Order refunded (webhook only)
—	`subscription`	Subscription started (webhook only)
(any name)	`custom`	Custom event

Core fields

Field	Type	Key	Description
Conversion ID	string	`conversion_id`	Unique ID for deduplication. Use your internal ID (order ID, lead ID, form submission ID, etc.). Always include this.
Value	number	`value`	Conversion value. Decimal, not cents (e.g., `99.00`).
Currency	string	`currency`	ISO 4217 code (e.g., `USD`, `EUR`, `GBP`).

`user_data` object

User data is used for session matching and enhanced conversion forwarding to ad platforms (Meta CAPI, Google Ads, TikTok Events API). TrustData hashes all fields before sending to any platform.

// SDK
trustdata.push(['event', 'generate_lead', {
  conversion_id: 'lead_abc789',
  value: 50,
  currency: 'USD',
  user_data: {
    email: '[email protected]',
    phone: '+15551234567',
    first_name: 'Jane',
    last_name: 'Doe',
    address: {
      street: '123 Main St',
      city: 'New York',
      region: 'NY',
      postal_code: '10001',
      country: 'US'
    }
  }
}]);

// Webhook — identical structure
{
  "conversion_id": "lead_abc789",
  "value": 50,
  "currency": "USD",
  "user_data": {
    "email": "[email protected]",
    "phone": "+15551234567",
    "first_name": "Jane",
    "last_name": "Doe",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "region": "NY",
      "postal_code": "10001",
      "country": "US"
    }
  }
}

`user_data` fields

Field	Type	Description
`user_data.email`	string	Customer email
`user_data.phone`	string	E.164 format (e.g., `+15551234567`)
`user_data.first_name`	string
`user_data.last_name`	string
`user_data.address.street`	string
`user_data.address.city`	string
`user_data.address.region`	string	State or province
`user_data.address.postal_code`	string	ZIP or postal code
`user_data.address.country`	string	ISO 3166-1 alpha-2 (e.g., `US`, `FR`)

`products` array

Line items for purchase events.

// SDK
trustdata.push(['event', 'purchase', {
  conversion_id: 'ORD-12345',
  value: 149.99,
  currency: 'USD',
  products: [
    {
      id: 'SKU123',
      name: 'Widget Pro',
      quantity: 2,
      price: 49.99,
    }
  ]
}]);

// Webhook — identical structure
{
  "conversion_id": "ORD-12345",
  "value": 149.99,
  "currency": "USD",
  "products": [
    {
      "id": "SKU123",
      "name": "Widget Pro",
      "quantity": 2,
      "price": 49.99
    }
  ]
}

`products` fields

Field	Type	Description
`id`	string	Product identifier
`name`	string	Product display name
`variant_id`	string	Variant identifier
`sku`	string	Stock keeping unit
`variant_title`	string	Variant name (e.g., `Blue / Large`)
`brand`	string	Brand name
`category`	string	Product category
`price`	number	Unit price
`quantity`	integer	Quantity ordered
`image_url`	string	Product image URL
`url`	string	Product page URL

Consent state for the event. Include this when you have explicit user consent information.

// SDK
trustdata.push(['event', 'purchase', {
  conversion_id: 'ORD-12345',
  value: 149.99,
  currency: 'USD',
  consent: {
    analytics: true,
    advertising: true
  }
}]);

// Webhook — identical structure
{
  "conversion_id": "ORD-12345",
  "value": 149.99,
  "currency": "USD",
  "consent": {
    "analytics": true,
    "advertising": true
  }
}

Field	Type	Description
`consent.analytics`	boolean	Analytics and measurement consent
`consent.advertising`	boolean	Ad targeting and remarketing consent
`consent.preferences`	boolean	Functional / preferences consent
`consent.sale_of_data`	boolean	Third-party data sharing opt-out (CCPA)

Purchase fields

Field	Type	Description
`tax`	number	Tax amount
`shipping`	number	Shipping cost
`discount_code`	string	Applied discount or coupon code
`discount`	number	Discount amount

Lead fields

Field	Type	Description
`lead_type`	string	Lead category (e.g., `demo_request`, `contact_form`, `newsletter`)

Custom fields

Any additional fields are stored as event metadata. They don't affect attribution or conversion forwarding.

What to send for maximum accuracy

Priority	Field	Why it matters
Critical	`conversion_id`	Prevents double-counting
Critical	`value` + `currency`	Required for ROAS and bidding signals
High	`user_data.email`	Session matching and enhanced conversions
High	Full `user_data`	Enables enhanced conversions to Meta, Google, TikTok
Medium	`products`	Product-level reporting and catalog matching
Medium	`consent`	Accurate consent-aware attribution
Low	Custom fields	Stored for analysis, not used for attribution

Events reference

Track page views and conversions with TrustData.

Overview

Connect your ad platforms into one unified data layer—no more conflicting reports.