Public event schema
The Apex analytics event wire format accepted by the Worker and written to Tinybird.
Apex events flow from the SDK, Shopify Pixel, external checkout pixels, or server integrations to the Worker, then to Tinybird. The shared @drip/event-schema package owns the public field list, validation patterns, and Tinybird column mapping.
Incoming event shape
The Worker accepts batches as an array of events, or as an object with an events array plus ingest auth:
{
"events": [
{
"type": "goal",
"eventId": "evt_demo_1001",
"shopId": "11111111-1111-4111-8111-111111111111",
"visitorId": "visitor_demo_123",
"sessionId": "session_demo_123",
"experimentId": "22222222-2222-4222-8222-222222222222",
"variationId": "33333333-3333-4333-8333-333333333333",
"url": "https://example.com/products/demo",
"data": {
"goalId": "__add_to_cart__",
"revenue": 49,
"currency": "EUR"
},
"ts": 1783502400000
}
],
"_shopId": "11111111-1111-4111-8111-111111111111",
"_signature": "px_signed_ingest_token_here"
}Accepted aliases:
| Canonical meaning | Accepted incoming keys |
|---|---|
| Shop ID | shop_id, shopId |
| Visitor ID | visitor_id, visitorId |
| Session ID | session_id, sessionId |
| User ID | user_id, userId |
| Event type | event_type, type |
| Event ID | event_id, eventId |
| Experiment ID | experiment_id, experimentId |
| Variation ID | variation_id, variationId |
| Properties | properties as a JSON object string or object, or data as an object |
| Timestamp | timestamp, ts |
event_type must match /^[a-zA-Z0-9_.:-]{1,120}$/. Properties must be a JSON object after normalization. Apex rejects common sensitive property names such as email, phone, password, ssn, credit_card, and card_number.
Outgoing field reference
After normalization, Apex writes these fields:
| Field | Required | Type or rule | Notes |
|---|---|---|---|
event_id | No | string | Generated when missing. Used for bounded dedupe when present. |
shop_id | Yes | string | Validated from ingest auth. |
visitor_id | Yes | string | Required after aliases; missing values are quarantined. |
session_id | Yes | string | Defaults to unknown if missing. |
user_id | Yes | string | Empty string when unknown. |
event_type | Yes | pattern string | Same pattern as incoming event_type. |
experiment_id | Yes | string | Empty string for unattributed events. |
variation_id | Yes | string | Empty string for unattributed events. |
url | Yes | string | Cleaned event URL. |
properties | Yes | JSON object string | Sanitized event properties plus event_id. |
bot | Yes | 0 or 1 | Worker bot evidence flag. |
live_run_id | Yes | string | Extracted from liveRunId or live_run_id; empty when absent. |
order_key | Yes | string | Derived from order, booking, checkout, or attribution properties. |
revenue | No | finite number | Promoted from properties when present and valid. |
currency | No | 3 uppercase letters | Promoted from currency, currencyCode, or currency_code. |
duration | No | finite number | Promoted from properties. |
scroll_depth | No | finite number | Promoted from scroll_depth or scrollDepth. |
goal_id | No | string | Promoted from goalId or goal_id. |
referrer | No | string | Promoted from properties. |
utm_source | No | string | Promoted from utm_source or utmSource. |
utm_medium | No | string | Promoted from utm_medium or utmMedium. |
utm_campaign | No | string | Promoted from utm_campaign or utmCampaign. |
device | Yes | string | Derived from the request user agent. |
country | Yes | string | Derived from Cloudflare request metadata or unknown. |
timestamp | Yes | parseable datetime string | Derived from timestamp, ts, or receipt time. |
qa_mode | Yes | 0 or 1 | 1 when incoming qa_mode is true. |
qa_session_id | Yes | string | Empty string when absent. |
user_id, experiment_id, variation_id, live_run_id, order_key, and qa_session_id intentionally use empty strings when absent for Tinybird compatibility.
Server API source requirements
Events sent with a tracking source key through x-apex-source-key or Authorization: Bearer apx_src_... must include a stable event_id. Apex uses that ID for replay protection and can quarantine missing IDs for server API sources.