Skip to content
trakbolt

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" with order_id and refunded_total (total refunded so far). A refund is never counted above the order value.
  • Order status: "event_name": "order_status" with order_id and status (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

StatusMeaningRetry?
400Invalid JSON or event; fields lists each problem (values are never echoed)No, fix the request
401Missing, wrong or disabled keyNo
413Body over 64 KBNo
429Over 600 events per minute for this key; Retry-After says whenYes, after the delay
5xx / networkA problem on Trakbolt's sideYes, 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.