Purchases from the server
The purchase of record comes from your server: purchase() in Node, or one HTTP call from any stack.
On this page
The purchase of record comes from your server, the way GA4 pairs a browser event with its Measurement Protocol. The browser gives Parlox the visit; your server confirms the order once it exists. Only a purchase from your server (or from Shopify's pixel) marks a visit "purchased".
How it fits together
- The page sends the visit's id with the checkout. Read it with
sessionId()from@parlox/browser, orwindow.parlox.sessionId()with the tag, and send it with the checkout request (a hidden field, a header, a property of the request body). - Your server stores it on the order.
- Once the order is paid, your server posts it to Parlox: the visit id, the order id, the total in cents and the currency.
import { sessionId } from "@parlox/browser";
await fetch("/api/checkout", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ cart, parloxSessionId: sessionId() }),
});sessionId() returns an id as soon as init has run (or the tag has loaded), also while Parlox waits for consent; it returns null only before that. An order posted without a visit id is still stored, keyed by its order id, but it cannot be joined to a visit.
Node: purchase()
import { createParlox } from "@parlox/server";
// A send key, in a variable of its own. PARLOX_SECRET_KEY keeps the crawler-reports-only key.
const orders = createParlox({ secretKey: process.env.PARLOX_ORDERS_KEY });
await orders.purchase({
sid: order.parloxSessionId,
order_id: "1001",
value_cents: 9980,
currency: "USD",
items: 2,
});purchase() is never batched: each order is posted at once, in a request of its own, with a two-second limit. The promise resolves { ok, status } and never rejects, so your checkout never fails because of it.
purchase() checks the order before sending it. If order_id is not a non-empty string, value_cents is not a whole number of 0 or more, or currency is not three capital letters, nothing is sent: the promise resolves { ok: false, status: 0 } and onError says which field. An unreadable sid is left out, and the order is still sent.
When Parlox refuses an order, the promise gives the status and onError gets Parlox's reason on one line (at most 300 characters, the key never included), for example:
Parlox refused the order (HTTP 403): This key can only send crawler reports. …At most 10 orders are posted at the same time in the process; beyond that the call resolves { ok: false, status: 0 } at once and onError says why, so your code can retry it.
The send key
Orders need a key with access "Send: crawler reports and orders". The key a new site gets, and every key the install wizard creates, can only send crawler reports, and an order sent with one is refused with 403.
- In the dashboard, open Settings → Keys and create a key with access "Send: crawler reports and orders".
- Set it on the server that posts orders, in a variable of its own, such as
PARLOX_ORDERS_KEY. Never under a name your frontend build exposes (VITE_…,NEXT_PUBLIC_…). - Pass it with the
secretKeyoption, as above. AsecretKeyyou pass is used alone: if the variable is unset, that instance sends nothing and says so once in your log. It never falls back toPARLOX_SECRET_KEY.
Keep the crawler-reports-only key in PARLOX_SECRET_KEY for the middleware. A send key could send crawler reports too, but in that variable, which a host's build can often read, it would let a leak record orders. Treat the send key as you treat a payment provider's secret key.
Any other stack: the order over HTTP
purchase() makes one HTTP request, and any server can make the same one. Post each order in a request of its own, from your server once the order is paid (in the code that records the payment, such as your payment provider's webhook handler), never from the browser.
POST https://gateway.parlox.io/v1/s
Authorization: Bearer $PARLOX_ORDERS_KEY
Content-Type: application/json
{"events":[{"event":"purchase","sid":"9f86d081884c7d659a2feaa0","order_id":"1001","value_cents":9980,"currency":"USD","items":2}]}The same request with curl:
curl -sS --max-time 2 -X POST "https://gateway.parlox.io/v1/s" \
-H "Authorization: Bearer $PARLOX_ORDERS_KEY" \
-H "Content-Type: application/json" \
-d '{"events":[{"event":"purchase","sid":"9f86d081884c7d659a2feaa0","order_id":"1001","value_cents":9980,"currency":"USD","items":2}]}'The fields
Parlox refuses no request for a field it cannot read: it drops that field, or the whole event, and answers as usual. So check them yourself.
| Field | Rule |
|---|---|
event | Exactly "purchase" |
order_id | Required, as a JSON string: "1001", not 1001 (a number is ignored, as if the field were missing). At most 64 characters; a longer one is cut |
value_cents | The order total in the currency's smallest unit, as a whole JSON number: 9980 for 99.80, not "9980" (a value in quotes is ignored, and the order is stored without its total) |
currency | The ISO 4217 code in capitals ("USD"). Any other form, such as "usd", is dropped and the order is stored without a currency |
sid | The session id saved on the order, as the browser gave it (sessionId() gives 24 lowercase hexadecimal characters; Parlox reads 16 to 32 of 0-9 and a-f). Leave it out when the order has none. An order without a sid Parlox can read is stored, keyed by its order id, but not joined to a visit |
items | Optional: the number of items in the order, as a JSON number |
The rules
- The key. A send key in a variable of its own, read only by the server code that posts orders. The "Crawler reports only" key in
PARLOX_SECRET_KEYis refused for orders. The header is exactlyAuthorization: Bearer <key>. - Timing. A two-second timeout, as
purchase()uses. Never let the call delay or fail the order or the customer's page: send it after your response or from a background job, and log a failure. - Once. Parlox does not deduplicate orders by
order_id: each order it accepts is stored as a new event, so send each order once. A429was refused before anything was written, and a503is a write the database did not confirm: send either again later. After a timeout with no answer, the order may have been stored.
The answers
| Status | Body | Meaning |
|---|---|---|
200 | {"accepted":1} | The request was read. accepted counts the events read from the body, not the orders stored: an event Parlox cannot use (an event name it does not know, such as "Purchase", or an order with neither an order_id nor a sid it can read) is counted but not stored. A body that is not JSON, or has no events list, gets {"accepted":0} |
401 | {"error":"Invalid secret key"} | No key, a key Parlox does not know, or one revoked or expired |
403 | {"error":"This key can only send crawler reports. To record orders or UCP reports, create a send key in the dashboard (Settings → Keys)."} | A "Crawler reports only" key |
429 | {"error":"Too many requests"} or {"error":"Too many requests for this key"} | Refused before anything was written. There is no Retry-After header |
413 | Payload Too Large (plain text) | The body is over 256 KB; nothing in it was read |
503 | {"error":"Write failed, retry later"} | The write was not confirmed |
Check it
Post a test order with a sid from a visit of your own (open your site, run window.parlox.sessionId() in the browser's console). In the dashboard's Visits view, that visit's timeline then shows the order, "confirmed by server", and its Reached field says Purchased.