Send orders from your server
If your store isn't on a connected sales platform, your system sends each sale to Clakta through the Orders API. Here is what to send and the mistakes to avoid.
If your store runs on Shopify, WooCommerce, Stripe or another connected sales platform, you don't need this: the connection sends your sales for you. This article is for stores whose system sends orders itself, and it needs a developer.
The script can't create orders: sales only reach Clakta from your server, through the Orders API.
The request
Create the key in Team settings → API keys and keep it on your server: it can write to your data. Every option is in the API reference.
What to send
Main fields
| Field | What it is |
|---|---|
projectId | The id or slug of the project the order belongs to. |
orderId | The order's id in your system. |
platform | Free text, such as shopify or the name of your own checkout. |
paymentMethod | credit_card, debit_card, pix, boleto, paypal, apple_pay, google_pay, samsung_pay, stripe_link or other. |
status | paid, pending, rejected, refunded or canceled. |
currency | Three-letter code, such as USD. The project currency if you leave it out. |
totalPrice | Number in the main unit: 10.4 means $10.40. |
products | Each with id, name, quantity and price. |
createdAt | Date and time of the order. Now, if you leave it out. |
approvedDate, refundedAt | Optional dates. |
The tracking object
This is what links the order to the ad. Send the values your site captured when the visitor arrived:
| Field | What it is |
|---|---|
clkt | The ad click parameter from the first page. Without it the order can never be credited to an ad. |
utm_* | The campaign UTM tags, kept for reports. |
sessionId | The visit the order belongs to. Ignored in privacy-friendly projects. |
domain | The site where the purchase happened. Required in privacy-friendly projects with more than one domain. |
Save these values on the cart or checkout when the shopper starts checkout, so your server still has them when the payment is approved.
Privacy-friendly projects
The order is the same, with one strict rule: customer can only contain ip
and userAgent. Sending id, name, email, phone, gender, dateOfBirth
or address makes Clakta reject the order.
Clakta uses the IP, the browser and the domain to find the visits from the same
day. sessionId is ignored.
This is the most common mistake. Your server sees its own address; you have to send the values your site saw for the shopper. If they are wrong, no order matches a visit and everything shows up as direct traffic.
Send the userAgent exactly as the browser sent it, without trimming or
changing anything.
Updating an order
Refunds and status changes use a PATCH:
You can change status, paymentMethod, platform, currency, totalPrice,
createdAt, approvedDate and refundedAt, and you have to send at least one
of them.
Tips
Related articles
How Clakta tracking works
The path from an ad click to a sale in Clakta, step by step, and where to look when something is missing.
Tracking modes
Privacy-friendly or full attribution: what each mode collects, what it costs you, and what changes when you switch.
Track ecommerce events
Record product views, add to cart, checkout started and payment submitted from your site, to see where visitors give up before buying.