Events and taxonomy

Every Kentro Pixel event, from the browser or from your server, uses one JSON envelope and one event name from a shared taxonomy. Each name has a JSON Schema, a consent purpose and a list of sources that make it authoritative; this page covers all three and how to check events before you send them.

In this page

• The envelope
• Context
• Money
• Email and phone identifiers
• How to read the taxonomy
• Standard taxonomy
• Which event should I send?
• Reserved for Kentro
• Custom events and the schema registry
• Validating events without sending them

The envelope

The SDK fills in ids, context and consent for you; server integrations build the envelope themselves.

{
  "event_id": "evt_192f0c51a2b9f3c7d1e5a2b4c6d8e0f",
  "event_name": "commerce.added_to_cart",
  "schema_version": 1,
  "occurred_at": "2026-10-09T17:00:00.000Z",
  "anonymous_id": "anon_6f1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e",
  "session_id": "sess_0a1b2c3d4e5f60718293a4b5",
  "subject_ref": null,
  "commerce_subject_ref": null,
  "order_ref": null,
  "campaign_ref": "cmp_spring_launch",
  "creative_ref": null,
  "landing_page_ref": null,
  "experiment_ref": null,
  "experiment_variant_ref": null,
  "context": {
    "page_url": "https://www.example.com/products/mug?utm_source=google&utm_medium=cpc&gclid=abc123",
    "page_title": "Mug",
    "referrer_domain": "www.google.com",
    "device_class": "desktop",
    "locale": "en-US",
    "sdk": { "name": "kentro-pixel-js", "version": "1.3.0" }
  },
  "consent": { "analytics": "granted", "marketing": "denied", "functional": "granted", "policy_version": "2026-10", "source": "cmp", "recorded_at": "2026-10-09T16:59:00Z", "region": "US-CA", "gpc": false },
  "properties": { "product_id": "sku-123", "quantity": 1, "unit_price": { "amount_minor": 1999, "currency": "USD" } }
}

An envelope may be at most 32 KB serialized. Unknown top-level fields are dropped. Kentro adds the workspace, property, source type, environment and receipt time itself.

Context

context accepts:

Property values whose key ends in url, uri, href, link or path get the same URL treatment as page_url.

Money

Money is always an object with integer minor units and an upper-case ISO 4217 code:

{ "amount_minor": 4999, "currency": "USD" }

4999 is 49.99 USD; for zero-decimal currencies such as JPY, amount_minor is the whole amount. Floats, strings and extra keys are rejected with SCHEMA_VIOLATION.

Email and phone identifiers

• Raw email and phone values at the top level of properties or under properties.customer are replaced on ingestion by email_sha256 and phone_sha256 (email trimmed and lower-cased, phone reduced to its digits, then SHA-256 as lower-case hex); the raw value is discarded.
• The builtin schemas accept identifiers only inside customer, so send properties.customer.email (or a pre-hashed email_sha256), never a top-level email. If you hash yourself, use the same normalization.
• The shared customer object accepts ref, email_sha256, phone_sha256, country (2 characters) and marketing_opt_in (boolean).
• In custom events, a top-level property whose name ends like a contact field (customer_email, email_address, phone_number, mobile) is replaced by <name>_sha256. In every event, email addresses inside other strings become [email] and phone numbers inside free text become [phone].

How to read the taxonomy

Three separate things describe every event:

• What happened: the namespace and the Category column. marketing.* events are website and acquisition behavior; commerce.* events are shopping and business records. The category ops marks Kentro GO operations, which Kentro GO records itself.
• Which consent it needs: the Consent purpose column. The purpose is fixed per event and does not follow the namespace. Most marketing.* website events need analytics consent; lead, opt-in and acquisition events need marketing consent; browser shopping events need analytics consent; order, payment, refund, return, subscription, customer and fulfillment records are functional.
• Whether it is a fact: the Authoritative from column. Orders, refunds and other revenue facts are authoritative only from a server source; a browser copy is accepted as a signal.

The purpose decides whether Kentro collects an event, not whether it is exported. Ad networks receive a person only with an explicit marketing grant, even for a functional order (see Destinations).

Standard taxonomy

Every builtin event has an allowlist of properties (additionalProperties is false), so unlisted keys are rejected. Strings are at most 256 characters unless the full schema says otherwise; counts are non-negative integers (quantity and step start at 1); items is an array of up to 200 line items (product_id and quantity required; variant_id, sku, name, category, unit_price and total optional). Browser or server covers browser, server, Shopify pixel, Kentro OS and Kentro GO landing pages; Server only covers the server API, Kentro OS, CRM and imports. Events from any other source are accepted but flagged is_authoritative: false. The full JSON Schemas are available from GET /v1/event-schemas.

• marketing.product_viewed is deprecated. Send commerce.product_viewed. The old name is still accepted, validated against its own schema, then recorded as commerce.product_viewed with product_name renamed to name. The per-event result carries "recorded_as": "commerce.product_viewed", and the event debugger shows "renamed_from": "marketing.product_viewed". Audience rules and destination mappings must use commerce.product_viewed.
• marketing.lead_qualified: send it from your server when a lead is qualified in your CRM or sales process. A browser copy is accepted but not authoritative.
• marketing.ad_clicked is optional: send it for an ad click you observed yourself, for example through a redirect service. Kentro already records ad clicks from the click ids on page views.

Which event should I send?

• One order counts once. Analytics keep one conversion per order reference: a server copy wins over a browser copy and commerce.order_paid over commerce.order_placed. Refunds and cancellations correct that conversion and never add a new one.
• One form submission counts once. Kentro GO landing pages send marketing.form_submitted (field names only) and marketing.lead_captured (hashed email and phone) for each submission; only marketing.lead_captured is a conversion. Lead events of the same type with the same lead_ref also count once.
• Conversion types. Conversion facts have one of seven types: lead_captured, signup_completed, demo_booked, order_placed and order_paid are conversions; order_refunded (full and partial refunds) and order_cancelled correct an order. These seven values are the only ones GET /v1/analytics/conversions?type= and audience conversion conditions accept. In Kentro GO, the Analytics page's Conversions view shows the totals by type.

Reserved for Kentro

Eighteen names describe facts Kentro computes itself, operations Kentro GO performs, or the history Kentro Email records. You cannot send them: every route (browser, batch, GIF beacon, server API and the validate endpoint) rejects them with RESERVED_EVENT, whatever the schema_version, with a reason that says what to use instead. GET /v1/event-schemas still lists them with reserved: true and that explanation in reserved_reason. Pixel audience rules and destination mappings that name them are refused.

Kentro Email segments can use the email.* events; Pixel audiences cannot. A Kentro Email link click also records an email touchpoint for attribution (see Processing).

Custom events and the schema registry

Custom event schemas are not available in this preview: you cannot create them, and the collector accepts the builtin taxonomy above. When they become available, these rules apply:

• A custom schema (an event name, a version, a category and a JSON Schema for properties) is validated exactly like a builtin. A builtin with the same name always wins, and a reserved name stays refused.
• Its consent purpose is functional when its category is ops and analytics otherwise; a custom event never has the marketing purpose.
• It is authoritative only when sent through the server API.
• Registry changes reach the collector within 60 seconds.

The schema listing:

Each builtin entry carries event_name, version, category, required, schema, authoritative_sources, consent_purpose, description, reserved, reserved_reason, replaced_by and builtin: true. replaced_by names the event a deprecated name is recorded as ("commerce.product_viewed" for marketing.product_viewed, null otherwise). Each custom entry carries event_name, version, category, schema, status, builtin: false, reserved: false, reserved_reason: null and replaced_by: null.

Validating events without sending them

POST /v1/event-schemas/validate runs the ingestion checks (envelope, clock skew, schema, identity tokens, sensitive-data detectors and the consent decision) on one envelope or { "events": [...] } (1 to 100), evaluated as browser events, and stores nothing.

• Authenticate with a property key (X-Kentro-Pixel-Key header, key query parameter or key in the body) on the collector host, or with your Kentro credentials on the management host. With a property key the property's settings apply; with Kentro credentials the default settings do.
• It does not check the origin allowlist, the per-key event rate limit or duplicates; requests count against the collector's per-IP limits.
• In Kentro GO, the property's Validate tab runs the same check.

curl -sS https://pixel.kentro.live/v1/event-schemas/validate \
  -H "X-Kentro-Pixel-Key: pk_live_Xq3M9b2LkV7tR1sNw8YhC4Ze" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "event_id": "evt_1", "event_name": "commerce.added_to_cart", "consent": { "analytics": "granted" }, "properties": { "product_id": "sku-1", "quantity": 1, "unit_price": { "amount_minor": 1999, "currency": "USD" } } },
      { "event_id": "evt_2", "event_name": "commerce.added_to_cart", "consent": { "analytics": "granted" }, "properties": { "product_id": "sku-1", "quantity": 1, "unit_price": { "amount_minor": 19.99, "currency": "USD" } } },
      { "event_id": "evt_3", "event_name": "marketing.product_viewed", "consent": { "analytics": "granted" }, "properties": { "product_id": "sku-1", "product_name": "Mug" } },
      { "event_id": "evt_4", "event_name": "marketing.purchase_attributed", "properties": { "order_ref": "order-1001", "model": "last_touch" } }
    ]
  }'

{
  "results": [
    { "index": 0, "event_id": "evt_1", "event_name": "commerce.added_to_cart", "valid": true, "outcome": "accepted", "reason_code": null },
    { "index": 1, "event_id": "evt_2", "event_name": "commerce.added_to_cart", "valid": false, "reason_code": "SCHEMA_VIOLATION", "reason": "properties/unit_price/amount_minor must be integer" },
    { "index": 2, "event_id": "evt_3", "event_name": "marketing.product_viewed", "valid": true, "outcome": "accepted", "reason_code": null, "recorded_as": "commerce.product_viewed" },
    { "index": 3, "event_id": "evt_4", "event_name": "marketing.purchase_attributed", "valid": false, "reason_code": "RESERVED_EVENT", "reason": "marketing.purchase_attributed is computed by Kentro attribution; read it from the attribution endpoints (GET /v1/analytics/attribution) instead of sending it" }
  ]
}

outcome is accepted, quarantined or suppressed, exactly what ingestion would record. recorded_as is present when the event was sent under a deprecated name.