On this page
Front-end tracking can be blocked by ad blockers and lost when someone closes the tab. For facts that have to be right — orders, payments, refunds, renewals — report them straight from your server.
1. Create an API key
The project owner or an admin creates a key under Configuration › Settings › API keys with the Server Track permission. Keys start with wck_ and are shown once, at creation. Put it in your secrets manager or environment variables right away.
Never put the key in front-end code, a repository or documentation. If it leaks, revoke it on the same page and create a new one.
2. Send an event
curl -X POST "https://api.pathclue.com/api/v1/track" \
-H "Authorization: Bearer wck_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"events":[{"event":"purchase","login_id":"u_1001","insert_id":"order-20261018-001","properties":{"revenue":49.9,"currency":"USD","order_id":"20261018-001"}}]}'The body is { "events": [ … ] } with 1 to 1,000 events. The key determines the project; there is no project ID parameter, and one isn't accepted.
Common fields
| Field | Required | Notes |
|---|---|---|
event | yes | Event name, up to 100 characters, same naming rules as the front end |
insert_id | recommended | Idempotency key, up to 36 characters. Resending the same key never adds a row; the first one wins |
login_id | no | The user ID in your system. With it, the event is attached to that user |
session_id | no | The session of the visit. Without it the event is stored but never counted as a new visit |
time | no | Milliseconds. If it's more than 72 hours from server time, the current time is used and a warning returned |
properties | no | Keys up to 50 characters; values are strings up to 1,000 characters, numbers, booleans or null |
Some advice:
- Always send
insert_id, using a naturally unique value such as the order or payment number. Then you can retry after a timeout without recording one order twice. - Commerce reports treat
purchaseas a purchase andrefundas a refund by default, readingrevenue,currencyandorder_id. Other names work too — map them under Product analytics › Configuration › Business settings. - Emails and phone numbers in identity fields that aren't already hashed are hashed for you, with a warning in the result.
3. Read the response
{ "received": 1, "accepted": 1, "rejected": 0, "events": 1, "results": [] }accepted— events that passed validation and were buffered.- When
rejectedis above 0,resultslists the position (index) and reason for each. Other events in the batch are still written. - 401 — the key is wrong, revoked, or lacks the Server Track permission.
While integrating, add ?debug=1 to the URL. The API validates and returns full results without storing anything.
4. Find it in reports
Look under Product analytics › Data management › Events & properties or Website analytics › Events. Events sent with login_id also appear on that user's profile.
Working alongside front-end events
Don't report the same thing from both sides, or it's counted twice. A split that works: the front end records intent ("clicked Buy now", "submitted order"), the server records outcomes (payment succeeded, refund completed). You get the drop-off in between and exact amounts.
Two other endpoints
Besides business events, two endpoints exist only to fill in bot data: submitting gateway access records and importing Nginx or Apache logs. They keep only requests identified as bots and can't be used for orders. See How bots and AI crawlers are identified.