Server-side tracking V2 - Dema.ai documentation

Supported event types

Required and optional event types

Prerequisites

What you need before getting started

Request details

Endpoint, methods, and parameters

Event examples

Sample payloads for each event type

Schema reference

Full TrackedEventData schema

Supported event types

The V2 API expects at minimum the following event types:

page_view

Page visits across your site

view_item

Product details page

purchase

Purchase transactions

The API also supports the following optional event types:

view_item_list

Product list viewed

select_item

Item selected from a list

add_to_cart

Item added to cart

remove_from_cart

Item removed from cart

view_cart

Cart page viewed

add_to_wishlist

Item added to wishlist

remove_from_wishlist

Item removed from wishlist

begin_checkout

Checkout started

The API is extensible — you can send any event_name value beyond the ones listed above, and Dema can build custom metrics on top of it. The available fields per event are defined by the event data schema.

Prerequisites

Your unique Dema ID, formatted as DV-XXXXXXXXXXXXXXXXXXXXXXXX

Response

The API returns an HTTP 200 status code with an empty response body on success.

Request details

Endpoint

URL: https://tracker.dema.ai/api/track

HTTP methods

Both GET and POST methods are supported.

GET requests have a practical limit of approximately 8 KB of data due to URL length restrictions. For larger payloads, use the POST method.

Required request parameters

Parameter	Description
`i`	Your unique Dema ID.
`uid`	Unique user ID for the event, a UUID managed server-side. Must be a valid UUIDv4 string. Should remain consistent across events for the same user.
`_nc`	No-cache parameter. Current timestamp in milliseconds since epoch.
`v`	Version of your tracking integration (e.g., `"2.0.0"`). Use your own versioning scheme.

Event details

For GET requests, event details are passed as a URL-encoded JSON string in the m query parameter. For POST requests, event details are sent as a JSON body with the Content-Type: application/json header. Event details must conform to the TrackedEventData schema. See the Event data schema reference section for the full schema and field descriptions.

Event examples

page_view

A basic page view event:

{
  "event_name": "page_view",
  "page_location": "https://example.com/summer-collection",
  "page_referrer": "https://google.com/search?q=summer+collection",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "ip": "10.0.0.1"
}

curl examples for page_view

DEMA_ID="YOUR-DEMA-ID"
USER_ID=$(uuidgen)
NC=$(date +%s%3N)

curl -X POST "https://tracker.dema.ai/api/track?i=${DEMA_ID}&uid=${USER_ID}&_nc=${NC}&v=2.0.0" \
  -H 'Content-Type: application/json' \
  -d '{
    "event_name": "page_view",
    "page_location": "https://example.com/summer-collection",
    "page_referrer": "https://google.com/search?q=summer+collection",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "ip": "10.0.0.1"
  }'

↑ Back to supported event types

view_item

Sent when a user views a product detail page:

{
  "event_name": "view_item",
  "page_location": "https://example.com/summer-collection/product1234",
  "page_referrer": "https://example.com/summer-collection",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "ip": "10.0.0.1",
  "items": [
    {
      "index": 0,
      "product_id": "1234",
      "price": 199.99
    }
  ],
  "currency": "EUR"
}

On a product display page, you should send both a page_view event and a view_item event. This is different from the deprecated V1 API, where a single pageview event covered both.

curl examples for view_item

DEMA_ID="YOUR-DEMA-ID"
USER_ID=$(uuidgen)
NC=$(date +%s%3N)

curl -X POST "https://tracker.dema.ai/api/track?i=${DEMA_ID}&uid=${USER_ID}&_nc=${NC}&v=2.0.0" \
  -H 'Content-Type: application/json' \
  -d '{
    "event_name": "view_item",
    "page_location": "https://example.com/summer-collection/product1234",
    "page_referrer": "https://example.com/summer-collection",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "ip": "10.0.0.1",
    "items": [
      {
        "index": 0,
        "product_id": "1234",
        "price": 199.99
      }
    ],
    "currency": "EUR"
  }'

↑ Back to supported event types

purchase

A purchase event, sent when a user completes a transaction:

{
  "event_name": "purchase",
  "page_location": "https://example.com/checkout",
  "page_referrer": "https://example.com/cart",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "ip": "10.0.0.1",
  "items": [
    {
      "index": 0,
      "product_id": "1234",
      "variant_no": "sku1234",
      "price": 199.99,
      "quantity": 1
    }
  ],
  "currency": "EUR",
  "total": 210.98,
  "tax": 42.20,
  "shipping": 19.99,
  "customer_id": "customer@example.com",
  "order_id": "45678"
}

curl examples for purchase

DEMA_ID="YOUR-DEMA-ID"
USER_ID=$(uuidgen)
NC=$(date +%s%3N)

curl -X POST "https://tracker.dema.ai/api/track?i=${DEMA_ID}&uid=${USER_ID}&_nc=${NC}&v=2.0.0" \
  -H 'Content-Type: application/json' \
  -d '{
    "event_name": "purchase",
    "page_location": "https://example.com/checkout",
    "page_referrer": "https://example.com/cart",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "ip": "10.0.0.1",
    "items": [
      {
        "index": 0,
        "product_id": "1234",
        "variant_no": "sku1234",
        "price": 199.99,
        "quantity": 1
      }
    ],
    "currency": "EUR",
    "total": 210.98,
    "tax": 42.20,
    "shipping": 19.99,
    "customer_id": "customer@example.com",
    "order_id": "45678"
  }'

↑ Back to supported event types

view_item_list

Sent when a user views a list of products (e.g., a category page or search results):

{
  "event_name": "view_item_list",
  "page_location": "https://example.com/summer-collection",
  "page_referrer": "https://google.com/search?q=summer+collection",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "ip": "10.0.0.1",
  "items": [
    {
      "index": 0,
      "product_id": "1234",
      "price": 199.99
    },
    {
      "index": 1,
      "product_id": "5678",
      "price": 49.99
    },
    {
      "index": 2,
      "product_id": "9012",
      "price": 89.99
    }
  ],
  "currency": "EUR"
}

curl examples for view_item_list

DEMA_ID="YOUR-DEMA-ID"
USER_ID=$(uuidgen)
NC=$(date +%s%3N)

curl -X POST "https://tracker.dema.ai/api/track?i=${DEMA_ID}&uid=${USER_ID}&_nc=${NC}&v=2.0.0" \
  -H 'Content-Type: application/json' \
  -d '{
    "event_name": "view_item_list",
    "page_location": "https://example.com/summer-collection",
    "page_referrer": "https://google.com/search?q=summer+collection",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "ip": "10.0.0.1",
    "items": [
      {
        "index": 0,
        "product_id": "1234",
        "price": 199.99
      },
      {
        "index": 1,
        "product_id": "5678",
        "price": 49.99
      },
      {
        "index": 2,
        "product_id": "9012",
        "price": 89.99
      }
    ],
    "currency": "EUR"
  }'

↑ Back to supported event types

select_item

Sent when a user selects a product from a list (e.g., a category page or search results). The index reflects the position where the item was presented to the user:

{
  "event_name": "select_item",
  "page_location": "https://example.com/summer-collection",
  "page_referrer": "https://google.com/search?q=summer+collection",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "ip": "10.0.0.1",
  "items": [
    {
      "index": 3,
      "product_id": "1234",
      "price": 199.99
    }
  ],
  "currency": "EUR"
}

curl examples for select_item

DEMA_ID="YOUR-DEMA-ID"
USER_ID=$(uuidgen)
NC=$(date +%s%3N)

curl -X POST "https://tracker.dema.ai/api/track?i=${DEMA_ID}&uid=${USER_ID}&_nc=${NC}&v=2.0.0" \
  -H 'Content-Type: application/json' \
  -d '{
    "event_name": "select_item",
    "page_location": "https://example.com/summer-collection",
    "page_referrer": "https://google.com/search?q=summer+collection",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "ip": "10.0.0.1",
    "items": [
      {
        "index": 3,
        "product_id": "1234",
        "price": 199.99
      }
    ],
    "currency": "EUR"
  }'

↑ Back to supported event types

add_to_cart

Sent when a user adds a product to their cart:

{
  "event_name": "add_to_cart",
  "page_location": "https://example.com/summer-collection/product1234",
  "page_referrer": "https://example.com/summer-collection",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "ip": "10.0.0.1",
  "items": [
    {
      "product_id": "1234",
      "variant_no": "sku1234",
      "price": 199.99,
      "quantity": 1
    }
  ],
  "currency": "EUR"
}

curl examples for add_to_cart

DEMA_ID="YOUR-DEMA-ID"
USER_ID=$(uuidgen)
NC=$(date +%s%3N)

curl -X POST "https://tracker.dema.ai/api/track?i=${DEMA_ID}&uid=${USER_ID}&_nc=${NC}&v=2.0.0" \
  -H 'Content-Type: application/json' \
  -d '{
    "event_name": "add_to_cart",
    "page_location": "https://example.com/summer-collection/product1234",
    "page_referrer": "https://example.com/summer-collection",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "ip": "10.0.0.1",
    "items": [
      {
        "product_id": "1234",
        "variant_no": "sku1234",
        "price": 199.99,
        "quantity": 1
      }
    ],
    "currency": "EUR"
  }'

↑ Back to supported event types

remove_from_cart

Sent when a user removes a product from their cart:

{
  "event_name": "remove_from_cart",
  "page_location": "https://example.com/cart",
  "page_referrer": "https://example.com/summer-collection/product1234",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "ip": "10.0.0.1",
  "items": [
    {
      "product_id": "1234",
      "variant_no": "sku1234",
      "price": 199.99,
      "quantity": 1
    }
  ],
  "currency": "EUR"
}

curl examples for remove_from_cart

DEMA_ID="YOUR-DEMA-ID"
USER_ID=$(uuidgen)
NC=$(date +%s%3N)

curl -X POST "https://tracker.dema.ai/api/track?i=${DEMA_ID}&uid=${USER_ID}&_nc=${NC}&v=2.0.0" \
  -H 'Content-Type: application/json' \
  -d '{
    "event_name": "remove_from_cart",
    "page_location": "https://example.com/cart",
    "page_referrer": "https://example.com/summer-collection/product1234",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "ip": "10.0.0.1",
    "items": [
      {
        "product_id": "1234",
        "variant_no": "sku1234",
        "price": 199.99,
        "quantity": 1
      }
    ],
    "currency": "EUR"
  }'

↑ Back to supported event types

view_cart

Sent when a user views their shopping cart:

{
  "event_name": "view_cart",
  "page_location": "https://example.com/cart",
  "page_referrer": "https://example.com/summer-collection/product1234",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "ip": "10.0.0.1",
  "items": [
    {
      "product_id": "1234",
      "variant_no": "sku1234",
      "price": 199.99,
      "quantity": 1
    },
    {
      "product_id": "5678",
      "variant_no": "sku5678",
      "price": 49.99,
      "quantity": 2
    }
  ],
  "currency": "EUR"
}

curl examples for view_cart

DEMA_ID="YOUR-DEMA-ID"
USER_ID=$(uuidgen)
NC=$(date +%s%3N)

curl -X POST "https://tracker.dema.ai/api/track?i=${DEMA_ID}&uid=${USER_ID}&_nc=${NC}&v=2.0.0" \
  -H 'Content-Type: application/json' \
  -d '{
    "event_name": "view_cart",
    "page_location": "https://example.com/cart",
    "page_referrer": "https://example.com/summer-collection/product1234",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "ip": "10.0.0.1",
    "items": [
      {
        "product_id": "1234",
        "variant_no": "sku1234",
        "price": 199.99,
        "quantity": 1
      },
      {
        "product_id": "5678",
        "variant_no": "sku5678",
        "price": 49.99,
        "quantity": 2
      }
    ],
    "currency": "EUR"
  }'

↑ Back to supported event types

add_to_wishlist

Sent when a user adds a product to their wishlist:

{
  "event_name": "add_to_wishlist",
  "page_location": "https://example.com/summer-collection/product1234",
  "page_referrer": "https://example.com/summer-collection",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "ip": "10.0.0.1",
  "wishlist_id": "wish-001",
  "items": [
    {
      "product_id": "1234",
      "price": 199.99
    }
  ],
  "currency": "EUR"
}

curl examples for add_to_wishlist

DEMA_ID="YOUR-DEMA-ID"
USER_ID=$(uuidgen)
NC=$(date +%s%3N)

curl -X POST "https://tracker.dema.ai/api/track?i=${DEMA_ID}&uid=${USER_ID}&_nc=${NC}&v=2.0.0" \
  -H 'Content-Type: application/json' \
  -d '{
    "event_name": "add_to_wishlist",
    "page_location": "https://example.com/summer-collection/product1234",
    "page_referrer": "https://example.com/summer-collection",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "ip": "10.0.0.1",
    "wishlist_id": "wish-001",
    "items": [
      {
        "product_id": "1234",
        "price": 199.99
      }
    ],
    "currency": "EUR"
  }'

↑ Back to supported event types

remove_from_wishlist

Sent when a user removes a product from their wishlist:

{
  "event_name": "remove_from_wishlist",
  "page_location": "https://example.com/wishlist",
  "page_referrer": "https://example.com/summer-collection/product1234",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "ip": "10.0.0.1",
  "wishlist_id": "wish-001",
  "items": [
    {
      "product_id": "1234",
      "price": 199.99
    }
  ],
  "currency": "EUR"
}

curl examples for remove_from_wishlist

DEMA_ID="YOUR-DEMA-ID"
USER_ID=$(uuidgen)
NC=$(date +%s%3N)

curl -X POST "https://tracker.dema.ai/api/track?i=${DEMA_ID}&uid=${USER_ID}&_nc=${NC}&v=2.0.0" \
  -H 'Content-Type: application/json' \
  -d '{
    "event_name": "remove_from_wishlist",
    "page_location": "https://example.com/wishlist",
    "page_referrer": "https://example.com/summer-collection/product1234",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "ip": "10.0.0.1",
    "wishlist_id": "wish-001",
    "items": [
      {
        "product_id": "1234",
        "price": 199.99
      }
    ],
    "currency": "EUR"
  }'

↑ Back to supported event types

begin_checkout

Sent when a user starts the checkout process:

{
  "event_name": "begin_checkout",
  "page_location": "https://example.com/checkout",
  "page_referrer": "https://example.com/cart",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "ip": "10.0.0.1",
  "items": [
    {
      "product_id": "1234",
      "variant_no": "sku1234",
      "price": 199.99,
      "quantity": 1
    },
    {
      "product_id": "5678",
      "variant_no": "sku5678",
      "price": 49.99,
      "quantity": 2
    }
  ],
  "currency": "EUR"
}

curl examples for begin_checkout

DEMA_ID="YOUR-DEMA-ID"
USER_ID=$(uuidgen)
NC=$(date +%s%3N)

curl -X POST "https://tracker.dema.ai/api/track?i=${DEMA_ID}&uid=${USER_ID}&_nc=${NC}&v=2.0.0" \
  -H 'Content-Type: application/json' \
  -d '{
    "event_name": "begin_checkout",
    "page_location": "https://example.com/checkout",
    "page_referrer": "https://example.com/cart",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "ip": "10.0.0.1",
    "items": [
      {
        "product_id": "1234",
        "variant_no": "sku1234",
        "price": 199.99,
        "quantity": 1
      },
      {
        "product_id": "5678",
        "variant_no": "sku5678",
        "price": 49.99,
        "quantity": 2
      }
    ],
    "currency": "EUR"
  }'

↑ Back to supported event types

Event data schema reference

The event detail payload must conform to the TrackedEventData schema. Below is a summary of the available fields.

View full TrackedEventData JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "TrackedEventData",
  "description": "Payload containing event data sent with a server-side tracking request.",
  "type": "object",
  "required": ["event_name"],
  "properties": {
    "event_name": {
      "type": "string",
      "description": "Name of the tracked event."
    },
    "type": {
      "type": "string",
      "description": "Event-specific type. For example, for order events the type can be set to `EXCLUDED` to prevent the order from appearing in the platform."
    },
    "user_agent": {
      "type": "string",
      "description": "User agent string of the client sending the tracked event."
    },
    "ip": {
      "type": "string",
      "description": "IP address sent in tracking event or resolved by the tracking system."
    },
    "country": {
      "type": "string",
      "description": "Two-letter ISO 3166-1 alpha-2 country code. When provided, overrides the country resolved from the IP address."
    },
    "region": {
      "type": "string",
      "description": "Region (state/province). When provided, overrides the region resolved from the IP address."
    },
    "zip_code": {
      "type": "string",
      "description": "ZIP/postal code. When provided, overrides the ZIP/postal code resolved from the IP address."
    },
    "city": {
      "type": "string",
      "description": "City. When provided, overrides the city resolved from the IP address."
    },
    "latitude": {
      "type": "number",
      "description": "Latitude coordinate. When provided, overrides the latitude resolved from the IP address."
    },
    "longitude": {
      "type": "number",
      "description": "Longitude coordinate. When provided, overrides the longitude resolved from the IP address."
    },
    "page_id": {
      "type": "string",
      "description": "Language-agnostic identifier of the page on which the event occurred."
    },
    "page_location": {
      "type": "string",
      "description": "Full URL of the page on which the event occurred."
    },
    "page_title": {
      "type": "string",
      "description": "Title of the page on which the event occurred."
    },
    "page_referrer": {
      "type": "string",
      "description": "Referrer URL from which the user navigated to the current page."
    },
    "cart_id": {
      "type": "string",
      "description": "Identifier of the shopping cart."
    },
    "wishlist_id": {
      "type": "string",
      "description": "Identifier of the wishlist."
    },
    "items": {
      "type": "array",
      "description": "List of items associated with the tracked event.",
      "items": {
        "$ref": "#/definitions/TrackedEventDataItem"
      }
    },
    "order_id": {
      "type": "string",
      "description": "Identifier of the order associated with the tracked event."
    },
    "currency": {
      "type": "string",
      "description": "Three letter ISO 4217 Currency code for the transaction."
    },
    "total": {
      "type": "number",
      "description": "Total value of the transaction, including items, tax and shipping."
    },
    "tax": {
      "type": "number",
      "description": "Total tax amount for the transaction including shipping tax."
    },
    "shipping": {
      "type": "number",
      "description": "Shipping cost for the transaction including tax."
    },
    "payment_provider": {
      "type": "string",
      "description": "Payment provider used for the transaction."
    },
    "shipping_provider": {
      "type": "string",
      "description": "Shipping provider used for the transaction."
    },
    "customer_id": {
      "type": "string",
      "description": "Identifier of the customer."
    },
    "vouchers": {
      "type": "array",
      "description": "List of vouchers applied in the transaction.",
      "items": {
        "$ref": "#/definitions/TrackedEventDataVoucher"
      }
    },
    "custom_attribute_1": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_2": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_3": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_4": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_5": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_6": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_7": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_8": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_9": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_10": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_11": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_12": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_13": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_14": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_15": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_16": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_17": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_18": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_19": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    },
    "custom_attribute_20": {
      "type": "string",
      "description": "Custom attribute on tracked event level."
    }
  },
  "additionalProperties": false,
  "definitions": {
    "TrackedEventDataItem": {
      "type": "object",
      "required": ["product_id"],
      "description": "Item line associated with a tracked event.",
      "properties": {
        "index": {
          "type": "integer",
          "description": "Index of the item line in the tracked event. This value is event context specific e.g. in select_item event it represents the index of the item in the list that was selected, in add_to_cart event it represents the index of the item in the cart etc."
        },
        "product_id": {
          "type": "string",
          "description": "Product identifier used for identifying the product in the external system."
        },
        "variant_no": {
          "type": "string",
          "description": "Identifier of the specific product variant."
        },
        "quantity": {
          "type": "number",
          "description": "Quantity of the item line."
        },
        "price": {
          "type": "number",
          "description": "Price of a single item unit."
        },
        "warehouse": {
          "type": "string",
          "description": "Warehouse associated with the item."
        },
        "custom_attribute_1": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_2": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_3": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_4": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_5": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_6": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_7": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_8": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_9": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_10": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_11": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_12": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_13": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_14": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_15": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_16": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_17": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_18": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_19": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        },
        "custom_attribute_20": {
          "type": "string",
          "description": "Custom attribute on tracked event item level."
        }
      },
      "additionalProperties": false
    },
    "TrackedEventDataVoucher": {
      "type": "object",
      "description": "A voucher (discount) applied to the transaction.",
      "required": ["code"],
      "properties": {
        "code": {
          "type": "string",
          "description": "The voucher's redemption code."
        },
        "name": {
          "type": "string",
          "description": "Voucher name."
        },
        "discount": {
          "type": "number",
          "description": "Value of the voucher discount."
        },
        "type": {
          "type": "string",
          "description": "Type of the discount."
        }
      },
      "additionalProperties": false
    }
  }
}

Event fields

Required fields

event_name

string

required

Name of the tracked event (e.g., page_view, view_item, purchase).

Page & navigation fields

Client & location fields

user_agent

string

User agent string of the client sending the tracked event.

string

IP address of the client. Used to resolve location fields if not provided explicitly.

country

string

Two-letter ISO 3166-1 alpha-2 country code. When provided, overrides the country resolved from the IP address.

region

string

Region (state/province). When provided, overrides the region resolved from the IP address.

city

string

City. When provided, overrides the city resolved from the IP address.

zip_code

string

ZIP/postal code. When provided, overrides the ZIP/postal code resolved from the IP address.

latitude

number

Latitude coordinate. When provided, overrides the latitude resolved from the IP address.

longitude

number

Longitude coordinate. When provided, overrides the longitude resolved from the IP address.

Event detail fields

type

string

Event-specific type. For example, for order events the type can be set to EXCLUDED to prevent the order from appearing in the platform.

order_id

string

Identifier of the order associated with the tracked event.

customer_id

string

Identifier of the customer. Typically an email address, but can be any consistent identifier.

currency

string

Three-letter ISO 4217 currency code (e.g., EUR, USD).

total

number

Total value of the transaction, including items, tax, and shipping.

tax

number

Total tax amount for the transaction including shipping tax.

shipping

number

Shipping cost for the transaction including tax.

payment_provider

string

Payment provider used for the transaction.

shipping_provider

string

Shipping provider used for the transaction.

cart_id

string

Identifier of the shopping cart.

wishlist_id

string

Identifier of the wishlist.

items

array

List of items associated with the event. See item fields below.

vouchers

array

List of vouchers applied to the transaction. See voucher fields below.

Custom attributes

custom_attribute_1 – custom_attribute_20

string

Custom attributes for event-level data.

Item fields (`items[]`)

Required fields

product_id

string

required

Product identifier used for identifying the product in the external system.

Optional fields

index

integer

Index of the item line in the tracked event. Event context specific — e.g., in select_item it represents the item’s position in the list; in add_to_cart it represents the item’s position in the cart.

variant_no

string

Identifier of the specific product variant.

quantity

number

Quantity of the item line.

price

number

Price of a single item unit.

warehouse

string

Warehouse associated with the item.

custom_attribute_1 – custom_attribute_20

string

Custom attributes for item-level data.

Voucher fields (`vouchers[]`)

Required fields

code

string

required

The voucher’s redemption code.

Optional fields

name

string

Voucher name.

discount

number

Value of the voucher discount.

type

string

Type of the discount.

Additional notes

Ensure all URL parameters are properly URL-encoded when using GET requests.
The uid (unique user ID) must be managed server-side. This ID should be a valid UUIDv4 and remain consistent across events to accurately track user behavior.

Documentation Index

Supported event types

Prerequisites

Request details

Event examples

Schema reference

​Supported event types

page_view

view_item

purchase

view_item_list

select_item

add_to_cart

remove_from_cart

view_cart

add_to_wishlist

remove_from_wishlist

begin_checkout

​Prerequisites

​Response

​Request details

​Endpoint

​HTTP methods

​Required request parameters

​Event details

​Event examples

​page_view

​view_item

​purchase

​view_item_list

​select_item

​add_to_cart

​remove_from_cart

​view_cart

​add_to_wishlist

​remove_from_wishlist

​begin_checkout

​Event data schema reference

​Event fields

​Item fields (items[])

​Voucher fields (vouchers[])

​Additional notes

Supported event types

Prerequisites

Response

Request details

Endpoint

HTTP methods

Required request parameters

Event details

Event examples

page_view

view_item

purchase

view_item_list

select_item

add_to_cart

remove_from_cart

view_cart

add_to_wishlist

remove_from_wishlist

begin_checkout

Event data schema reference

Event fields

Item fields (`items[]`)

Voucher fields (`vouchers[]`)

Additional notes