Payload Reference

Every event sent to POST /collect/{api_key} is a JSON envelope. Identity and context live at the top level; the event's own payload — value, currency, products — lives in a nested data object.

Envelope shape

{
  "event":     "purchase",          // top-level: the event name
  "event_id":  "purchase_ORD-001",  // top-level: deduplication
  "client_id": "cl_abc123",         // top-level: matching
  "data": {                         // ← all event/commerce fields go here
    "value":    99.80,
    "currency": "EUR",
    "order_id": "ORD-001",
    "contents": [
      { "id": "SKU-1", "name": "Sneaker X", "price": 49.90, "quantity": 2 }
    ]
  },
  "user": {                         // top-level: PII, hashed server-side
    "email": "customer@example.com"
  }
}

The three layers of the envelope:

• Top level — the event name (event), identity and context fields (event_id, client_id, session_id, page, utm, consent) and the two nested objects data and user. On the REST API v2 the event-name field is called event_name instead of event.
• data — the event's own payload: monetary value, currency, order and product fields. For purchase and refund, data.value and data.currency are required. contents[] accepts items as an alias.
• user — personally identifiable information. Pass plaintext; Tugus hashes email, phone, names and external_id with SHA-256 before forwarding. Click identifiers (fbp, fbc, gclid, …) are non-PII and passed through as-is.

Field reference

The complete, authoritative field list — every top-level, data, contents[] and user field with its type and whether it is required — is generated from the OpenAPI spec and lives on the collect endpoint reference. It is always in sync with the API; this page only explains the envelope structure.