Reference

Pixel · server events

Report conversions from your own backend, so the ones an ad blocker eats in the browser still reach Klozzo.

Authenticate with your site's secret key as a Bearer token. It is shown once, when the site is created, and only its hash is stored — if it is lost it can be reissued, never recovered.

Send the visitor's anonymous_id and everything changes. The pixel puts it into every form on your site as a hidden kz_anonymous_id field, so your backend already receives it with the submission — store it with the order and send it back here. Without it the event still lands, but as an orphan: a purchase with no browsing behind it, no source, no session, nothing to explain where the customer came from. This is the single most common way a server-side integration ends up worth half of what it could be.

Report events from a server

Reports events your own server knows about — a purchase, a refund, a renewal — up to 500 in one batch. Unlike the browser endpoint, a batch is not rejected as a whole: the valid events are accepted and the rest are reported back with the reason. A backend can act on a partial answer; a browser cannot, which is why the two behave differently.

POST /api/v1/events

Body parameters

anonymous_id string

The visitor's id, from the hidden kz_anonymous_id field your form received.

Example: 0d5b6b6e-3e1f-4a5e-9a0a-6c4b0e4b1a2c
events object[] required

The events to record.
- event_id string required
  
  Your id for this event; the same value the browser used, if it also reported it.
  
  Example: ord_10293
- action_source string required
  
  Always server.
  
  Example: server
- name string required
  
  Example: purchase
- anonymous_id string
  
  Must be a valid UUID.
  
  Example: 6b72fe4a-5b40-307c-bc24-f79acf9a1bb9
- occurred_at string
  
  When it happened. Within 7 days past and 5 minutes future.
  
  Example: 2026-08-02T18:04:00-06:00
- url string
  
  The full URL where it happened.
  
  Example: https://example.com/checkout/gracias
- path string
  
  The path alone, if you would rather not send the query string.
  
  Example: /checkout/gracias
- value number
  
  The amount, for monetary events.
  
  Example: 1899.5
- currency string
  
  ISO 4217.
  
  Example: MXN
- properties object
  
  Anything else about the event.
  
  Example: {"order_id":"ORD-10293"}
- traits object
  
  Identity fields (email, phone, first_name, last_name, company).
  
  Example: {"email":"ana@tienda.test"}

curl --request POST \
    "https://klozzo.com/api/v1/events" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"anonymous_id\": \"0d5b6b6e-3e1f-4a5e-9a0a-6c4b0e4b1a2c\",
    \"events\": [
        {
            \"event_id\": \"ord_10293\",
            \"action_source\": \"server\",
            \"name\": \"purchase\",
            \"anonymous_id\": \"6b72fe4a-5b40-307c-bc24-f79acf9a1bb9\",
            \"occurred_at\": \"2026-08-02T18:04:00-06:00\",
            \"url\": \"https:\\/\\/example.com\\/checkout\\/gracias\",
            \"path\": \"\\/checkout\\/gracias\",
            \"value\": 1899.5,
            \"currency\": \"MXN\",
            \"properties\": {
                \"order_id\": \"ORD-10293\"
            },
            \"traits\": {
                \"email\": \"ana@tienda.test\"
            }
        }
    ]
}"

const url = new URL(
    "https://klozzo.com/api/v1/events"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "anonymous_id": "0d5b6b6e-3e1f-4a5e-9a0a-6c4b0e4b1a2c",
    "events": [
        {
            "event_id": "ord_10293",
            "action_source": "server",
            "name": "purchase",
            "anonymous_id": "6b72fe4a-5b40-307c-bc24-f79acf9a1bb9",
            "occurred_at": "2026-08-02T18:04:00-06:00",
            "url": "https:\/\/example.com\/checkout\/gracias",
            "path": "\/checkout\/gracias",
            "value": 1899.5,
            "currency": "MXN",
            "properties": {
                "order_id": "ORD-10293"
            },
            "traits": {
                "email": "ana@tienda.test"
            }
        }
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://klozzo.com/api/v1/events';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'anonymous_id' => '0d5b6b6e-3e1f-4a5e-9a0a-6c4b0e4b1a2c',
            'events' => [
                [
                    'event_id' => 'ord_10293',
                    'action_source' => 'server',
                    'name' => 'purchase',
                    'anonymous_id' => '6b72fe4a-5b40-307c-bc24-f79acf9a1bb9',
                    'occurred_at' => '2026-08-02T18:04:00-06:00',
                    'url' => 'https://example.com/checkout/gracias',
                    'path' => '/checkout/gracias',
                    'value' => 1899.5,
                    'currency' => 'MXN',
                    'properties' => ['order_id' => 'ORD-10293'],
                    'traits' => ['email' => 'ana@tienda.test'],
                ],
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://klozzo.com/api/v1/events'
payload = {
    "anonymous_id": "0d5b6b6e-3e1f-4a5e-9a0a-6c4b0e4b1a2c",
    "events": [
        {
            "event_id": "ord_10293",
            "action_source": "server",
            "name": "purchase",
            "anonymous_id": "6b72fe4a-5b40-307c-bc24-f79acf9a1bb9",
            "occurred_at": "2026-08-02T18:04:00-06:00",
            "url": "https:\/\/example.com\/checkout\/gracias",
            "path": "\/checkout\/gracias",
            "value": 1899.5,
            "currency": "MXN",
            "properties": {
                "order_id": "ORD-10293"
            },
            "traits": {
                "email": "ana@tienda.test"
            }
        }
    ]
}
headers = {
  'Authorization': 'Bearer {YOUR_API_TOKEN}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

{
    "received": 2,
    "rejected": 1,
    "errors": {
        "1": [
            "`purchase` needs a `value`."
        ]
    }
}

received integer
rejected integer
errors object
- 1 string[]

{
    "message": "A Bearer token with your site secret key is required."
}

Every error shares the same shape — message and errors. See Errors.

{
    "message": "Falta events.",
    "errors": {
        "events": [
            "Falta events."
        ]
    }
}

Every error shares the same shape — message and errors. See Errors.

{
    "message": "Events no puede tener más de 500 elementos.",
    "errors": {
        "events": [
            "Events no puede tener más de 500 elementos."
        ]
    }
}

Every error shares the same shape — message and errors. See Errors.

{
    "message": "Too Many Attempts."
}

Every error shares the same shape — message and errors. See Errors.