Send orders from your server
Completed purchases reach Clakta only through the authenticated Orders API. Here is the payload, the tracking context you must forward, and how to keep it idempotent.
The tracking script can report that a payment was submitted, but it can never create a completed order. Orders exist only through the authenticated Orders API, called from your backend — anything the browser can send, a hostile browser can forge.
The request
curl -X POST https://api.clakta.com/v1/orders \
-H "Authorization: Bearer $CLAKTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ ... }'Create the key under Team settings → API keys. Keep it on the server — it carries write access to your data.
Full endpoint documentation, including every response code, lives in the API reference.
Payload
{
"projectId": "proj_3c17f5a2",
"orderId": "1042",
"platform": "shopify",
"paymentMethod": "credit_card",
"status": "paid",
"currency": "USD",
"totalPrice": 59.98,
"products": [
{ "id": "sku-1042", "name": "Blue shirt", "quantity": 2, "price": 29.99 }
],
"customer": {
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+15551234567",
"gender": "male",
"dateOfBirth": "1990-03-05",
"address": {
"city": "New York",
"state": "NY",
"postalCode": "10001",
"country": "us"
},
"ip": "203.0.113.42",
"userAgent": "Mozilla/5.0 ..."
},
"tracking": {
"clkt": "fb:facebook:120210000000:120211111111:120212222222",
"utm_source": "facebook",
"utm_medium": "cpc",
"utm_campaign": "summer-sale",
"utm_content": "video-a",
"domain": "shop.example.com",
"sessionId": "..."
},
"createdAt": "2026-01-30T12:00:00.000Z",
"approvedDate": "2026-01-30T12:04:21.000Z"
}Core fields
| Field | Notes |
|---|---|
projectId | The project id or slug that owns the order. |
orderId | The order's id in your system. |
platform | Free text — shopify, woocommerce, your own checkout. |
paymentMethod | credit_card, debit_card, pix, boleto, paypal, apple_pay, google_pay, samsung_pay, stripe_link. |
status | paid, pending, rejected, refunded, canceled. |
currency | ISO 4217. Defaults to the project currency if omitted. |
totalPrice | Float in major units — 10.4 means $10.40. |
products | Each with id, name, quantity, price. |
createdAt | ISO 8601. Defaults to now. |
approvedDate, refundedAt | ISO 8601, optional. |
The tracking object
This is what makes the order attributable. Forward the values your storefront captured in the browser:
| Field | Notes |
|---|---|
clkt | The ad click parameter from the landing URL. Without it the order can never be credited to an ad. |
utm_* | Standard campaign parameters, kept for reporting. |
sessionId | The browser session the order belongs to. Ignored in privacy-friendly projects. |
domain | The hostname the purchase originated on. Required for privacy-friendly projects with more than one tracking domain. |
You will need to persist these on your cart or checkout record when the shopper starts checkout, so your backend still has them when payment completes.
Privacy-friendly projects
The payload shape is the same with one hard rule: the customer object may
contain only ip and userAgent. Any of id, name, email, phone,
gender, dateOfBirth or address causes the request to be rejected.
{
"customer": {
"ip": "203.0.113.42",
"userAgent": "Mozilla/5.0 ..."
}
}The server recomputes the anonymous daily session hash from the IP, User-Agent
and domain, and uses it to match the order to its page views. sessionId is
ignored.
This is the single most common integration bug. Your backend sees its own address; you must forward the values your storefront observed for the shopper. Get them wrong and every order gets a fresh anonymous identity, matches nothing, and shows up as direct traffic.
The User-Agent must be the raw header string, byte for byte. It is hashed verbatim, so trimming or normalizing it breaks the match.
Updating an order
Refunds and status changes go through a PATCH:
curl -X PATCH https://api.clakta.com/v1/orders/1042 \
-H "Authorization: Bearer $CLAKTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "projectId": "proj_3c17f5a2", "status": "refunded" }'Only status and paymentMethod are updatable, and at least one must be
present.
Practical advice
Related
Related articles
How Clakta tracking works
The path a visitor takes from an ad click to an attributed order, and which part of the system is responsible for each step.
Tracking modes
Privacy-friendly or full attribution — what each mode collects, how sessions are built in each, and what changes in your data when you switch.
Track ecommerce events
Record product views, add to cart, checkout start and payment submitted from the browser — and understand why completed purchases are not in this list.