Server events API
One format for every system: your CRM, shop backend or a partner forwarder posts the same JSON.
Get a key
Settings → Integrations → Server events → Create source key (workspace admins). The key is shown once. Use one key per sending system.
Send an event
POST https://<your Trakbolt host>/api/v1/events
Authorization: Bearer wpk_…
Content-Type: application/json
{
"event_id": "order-1001-paid", // required: a resend with the same id is a duplicate, never counted twice
"event_name": "checkout_completed", // required: a standard event name, or your own
"occurred_at": "2026-11-11T10:15:00Z", // ISO 8601 (no zone = UTC) or epoch seconds / ms
"join_keys": { "ref_id": "abc123" }, // ids the visitor carried into your app
"user": {
"email": "buyer@example.com", // hashed on arrival; raw values are not stored
"phone": "+1 555 010 0000",
"external_id": "customer-42", // your stable customer id
"visitor_id": "Q2x…" // the wp_vid Trakbolt added to links into your app
},
"order_id": "1001",
"value": 199.00, // major units
"currency": "USD",
"items": [{ "id": "sku-7", "category": "cat-a", "price": 199.00, "quantity": 1 }],
"utm": { "source": "google", "campaign": "brand" },
"click_ids": { "gclid": "…" },
"clicked_at": "2026-11-11T10:02:00Z", // when the visitor clicked that ad, if you know it
"consent": "accepted", // your record of tracking consent; declined is never overruled
"test": false // true = kept, flagged, never sent to ad platforms
}- Refunds:
"event_name": "refund"withorder_idandrefunded_total(total refunded so far). A refund is never counted above the order value. - Order status:
"event_name": "order_status"withorder_idandstatus(shipped, canceled…). - clicked_at: send it when your events repeat the landing's ad data after the click, so the ad touch is dated at the click. It is ignored when it is after the event or more than 90 days before it.
- A time more than five minutes in the future is read as the time Trakbolt received the event.
- Unknown fields are refused (400), so typos and stray personal data never get in. Bodies are limited to 64 KB.
Reply
200 { "status": "accepted", "event_id": "…", "matched_by": "join_key", "person_id": "…" }
200 { "status": "duplicate", "event_id": "…" }matched_by says how the event reached a visit: see How Trakbolt works. An event that arrives before its visit can join later; it then shows as matched_late.
Errors and retries
| Status | Meaning | Retry? |
|---|---|---|
| 400 | Invalid JSON or event; fields lists each problem (values are never echoed) | No, fix the request |
| 401 | Missing, wrong or disabled key | No |
| 413 | Body over 64 KB | No |
| 429 | Over 600 events per minute for this key; Retry-After says when | Yes, after the delay |
| 5xx / network | A problem on Trakbolt's side | Yes, with backoff and the same event_id |
Your own format: field mapping
A source can carry a field mapping (Settings → Integrations → the source), so your system posts its payload as it already is. Each row maps one of your fields to a Trakbolt field, with optional transforms (trim, lowercase, uppercase, number, string, boolean, minor_to_major, url_without_query, sha256). Fields without a row are dropped and never stored. Suggest proposes rows from the field names your source has sent.