DEVELOPERS
TrackPilot REST API v1
Send server-side events from any backend (Laravel, Node, Shopify app, ERP…), confirm or cancel cash-on-delivery orders, and read your tracking reports. JSON in, JSON out.
Base URL & authentication
https://trackpilot.cognifyx.net/api/v1
Create a key under Settings → API keys in your dashboard and send it with every request:
Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxx
Keys are per workspace. Read only keys can call GET endpoints; read + write keys can also send events and order updates. Limit: 300 requests / minute / key (HTTP 429 when exceeded). Errors always look like {"error": {"code": "…", "message": "…"}}.
Endpoints
| Endpoint | What it does |
|---|---|
GET/me | Workspace, plan, this month's usage, key scope. |
GET/containers | Your websites (id, key, domain, COD hold setting). |
GET/containers/{id or key} | One website with its receivers (Meta, TikTok, GA4…). |
POST/events | Send a server-side event. Deduplicated with the browser copy by event_id. Needs write access. |
GET/events | List events. Filters: container, event_name, status, order_id, since, before, limit (≤200). |
GET/events/{id or event_id} | One event with every delivery (per platform status + error). |
POST/orders/{order_id}/status | Confirm / cancel / deliver a COD order → releases or drops the held Purchase. Needs write access. |
POST/offline-orders | Phone / WhatsApp / Messenger orders (one, or up to 500) → Purchase with action source phone_call / chat for Meta, TikTok offline events and GA4. Needs write access. |
GET/held | Purchases currently on hold (COD), oldest first. |
GET/reports/summary?days=7&container=… | Events, delivery rate per platform, purchases + value, COD outcome, match quality, daily series. |
GET/usage | Events used this month vs the plan limit. |
Send an event
Use the same event_id your browser pixel uses (for example order-1234) so Meta / TikTok count the purchase once. Personal data is hashed on our side before it leaves the server — send it raw.
curl -X POST https://trackpilot.cognifyx.net/api/v1/events \
-H "Authorization: Bearer tp_live_…" \
-H "Content-Type: application/json" \
-d '{
"container": "YOUR_WEBSITE_KEY",
"event_name": "Purchase",
"event_id": "order-1234",
"event_time": "2026-10-19T10:00:00Z",
"url": "https://shop.example.com/checkout/thank-you",
"order_id": "1234",
"user_data": {
"email": "customer@example.com", "phone": "01712345678",
"first_name": "Rahim", "last_name": "Uddin", "city": "Dhaka", "country": "bd",
"external_id": "cust-88", "client_ip_address": "103.1.2.3",
"client_user_agent": "Mozilla/5.0 …", "fbc": "fb.1.1700000000.AbCd", "fbp": "fb.1.1700000000.12345"
},
"custom_data": {"value": 1500, "currency": "BDT", "content_ids": ["SKU-1"], "num_items": 1},
"click_ids": {"fbclid": "…", "gclid": "…", "ttclid": "…"}
}'
Response 201 (or 200 when the same event_id already existed):
{"accepted": true, "duplicate": false,
"event": {"id": "…", "event_name": "Purchase", "status": "held",
"deliveries": []}}
status is processed (sent to every receiver), held (COD hold — waiting for an order update), over_quota or dropped. Standard names: PageView, ViewContent, AddToCart, InitiateCheckout, Purchase, Lead, CompleteRegistration, Contact, Subscribe — anything else is forwarded as a custom event.
Confirm or cancel a COD order
curl -X POST https://trackpilot.cognifyx.net/api/v1/orders/1234/status \
-H "Authorization: Bearer tp_live_…" \
-H "Content-Type: application/json" \
-d '{"container": "YOUR_WEBSITE_KEY", "status": "confirmed"}'
status: confirmed or delivered → the held Purchase is sent to Meta / TikTok / GA4 with its original time; cancelled → it is dropped. Any word from the website's status mapping (e.g. processing, returned) works too. Response: {"action": "released" | "dropped" | "none" | "already_processed", "matched": 1}.
Phone & WhatsApp orders
Orders taken by phone call, WhatsApp, Messenger or in a shop can be counted in your ads too. The customer's phone number is the match key — Meta and TikTok link it to the person who saw or clicked the ad. Send each order once when it is created (and again with a new status later — the same order_id is never counted twice), or only when it is delivered.
curl -X POST https://trackpilot.cognifyx.net/api/v1/offline-orders \
-H "Authorization: Bearer tp_live_…" \
-H "Content-Type: application/json" \
-d '{"container": "YOUR_WEBSITE_KEY",
"orders": [
{"order_id": "1001", "phone": "01712345678", "name": "Rahim Uddin", "value": 1500, "currency": "BDT",
"source": "phone", "status": "delivered", "order_date": "2026-10-30T14:05:00+06:00", "items": 1, "city": "Dhaka"},
{"order_id": "1002", "phone": "+8801812345678", "value": 2450, "source": "whatsapp", "status": "pending"}
]}'
| Field | Meaning |
|---|---|
order_id * | Your order number. Also used to avoid double counting with the website's own Purchase. |
phone * (or email) | 01XXXXXXXXX or +8801XXXXXXXXX — hashed before it leaves our server. |
source | phone (default) → Meta action_source phone_call; whatsapp / messenger / instagram → chat; offline → other. |
status | pending (held when COD hold is on), confirmed / delivered (sent now), cancelled (never sent). Update later with POST /orders/{order_id}/status. |
order_date | ISO date-time or YYYY-MM-DD; must be within the last 7 days (Meta / TikTok limit). Default: now. |
Response: {"summary": {"sent": 1, "held": 1}, "results": [{"order_id": "1001", "result": "sent", …}]}. Results: sent, held, duplicate, skipped_cancelled, over_quota, dropped (an Event Rule), invalid (see message). TikTok needs an offline event set ID on its receiver; Google Ads, Snapchat, Pinterest and LinkedIn do not receive offline orders.
Read events & reports
GET https://trackpilot.cognifyx.net/api/v1/events?container=YOUR_WEBSITE_KEY&event_name=Purchase&since=2026-10-01T00:00:00Z&limit=100
GET https://trackpilot.cognifyx.net/api/v1/events/order-1234
GET https://trackpilot.cognifyx.net/api/v1/held?container=YOUR_WEBSITE_KEY
GET https://trackpilot.cognifyx.net/api/v1/reports/summary?days=30
Lists are newest first. When has_more is true, call again with before=<next_before>.
Webhooks the other way
You do not need the API to confirm orders from WooCommerce, Steadfast, Pathao, RedX, Google Sheets or n8n — every website has a ready-made webhook URL and courier connectors under Order Status. The API is for your own code.
Error codes
| HTTP | code | Meaning |
|---|---|---|
| 400 | bad_request / invalid_json | Missing or malformed field — the message says which. |
| 401 | unauthorized | Missing, unknown or revoked key. |
| 403 | read_only_key / container_inactive / workspace_suspended | Key has no write access, or the website / workspace is off. |
| 404 | not_found | Unknown website or event in this workspace. |
| 429 | rate_limited | Slow down — 300 requests per minute per key. |
Platform status: trackpilot.cognifyx.net/status/ · Questions: যোগাযোগ