Report paid orders
- Path
/carts- Auth
- Secret key · server only
const url = 'https://releva.ai/api/v0/carts';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"carts":[{"orderId":"DEMO-ORDER-1001","cartPaid":true,"email":"taylor@example.com","products":[{"id":"DEMO-1001","price":39.9,"currency":"EUR","quantity":1},{"id":"DEMO-1002","price":19.2,"currency":"EUR","quantity":2}]}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://releva.ai/api/v0/carts \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "carts": [ { "orderId": "DEMO-ORDER-1001", "cartPaid": true, "email": "taylor@example.com", "products": [ { "id": "DEMO-1001", "price": 39.9, "currency": "EUR", "quantity": 1 }, { "id": "DEMO-1002", "price": 19.2, "currency": "EUR", "quantity": 2 } ] } ] }'Records paid orders for the domain that owns the secret key. Orders drive store revenue, attribution and
order-based segments.
Each cart needs at least one of email, phoneNumber or profileId. Carts without one are skipped and the
rest of the batch is processed; if no cart has one, the request is rejected with 400.
An orderId is recorded once per domain: a repeated orderId is accepted and ignored (only its cart-level
custom fields are merged onto the stored order), so retries never double revenue.
Processing is asynchronous: orders are held for about 30 seconds so a matching browser checkout event can be
merged, then recorded. A cart with cartPaid: false records no order.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
At least one of email, phoneNumber or profileId is required (checked after schema validation).
object
Your order id. Recorded once per domain; repeats are ignored. The length limit is enforced by storage, not by validation.
Send true. false records no order and no revenue.
Shopper’s email. null is treated as absent.
International format, + followed by digits. Before validation, non-digits are removed, a leading 00
becomes +, and a number starting with 0 or a digit gets the domain country’s dialling code.
null is treated as absent.
Your own customer id.
Profiles to merge into this shopper’s profile, such as the anonymous id of a guest checkout.
Order time with seconds and a timezone offset. Defaults to the time of the request.
B2B company id.
object
object
object
object
true records privacy policy consent on the profile.
The shopper’s browser user agent (not your server’s). Used for ad-platform matching.
The shopper’s IP address (not your server’s). Used for ad-platform matching.
Storefront URL the order was completed on.
Order address for ad-platform advanced matching.
object
Region code
ISO-3166-1 alpha-2 code, such as BG.
Deduplication id shared with your browser pixel, forwarded to ad platforms.
object
Catalog product id (as sent to POST /products). Used to copy product attributes onto the order.
Purchased variant id.
Unit price. Must be a JSON number.
Units purchased.
ISO-4217 code. Omit only when the price is in the domain currency.
object
object
object
object
Example
{ "carts": [ { "orderId": "DEMO-ORDER-1001", "cartPaid": true, "email": "taylor@example.com", "products": [ { "id": "DEMO-1001", "price": 39.9, "currency": "EUR", "quantity": 1 }, { "id": "DEMO-1002", "price": 19.2, "currency": "EUR", "quantity": 2 } ] } ]}Responses
Section titled “Responses”Accepted for asynchronous processing.
object
Example
{}Authentication or validation error, or no cart carries an identifier.
object
Human-readable error. Several validation errors are joined with a space.
Examples
{ "message": "Authorization header is missing."}{ "message": "Domain with the provided secret key cannot be found."}{ "message": "The 'carts' field must contain at least 1 items."}{ "message": "The 'carts[0].orderId' field is required."}{ "message": "For each cart, at least one of (email, phoneNumber, profileId) is required!"}{ "message": "carts[0].timestamp must be a valid ISO-8601 date including seconds and timezone offset with optional milliseconds such as 2020-01-01T23:59:59.999Z or 2020-01-01T23:59:59.999-0500 or 2020-01-01T23:59:59-0500. Got 2026-03-27 instead."}{ "message": "The object 'carts[0]' contains forbidden keys: 'total'."}{ "message": "carts[0].products[0].currency must be a valid ISO-4217 currency code! Got EURO instead."}{ "message": "The 'carts[0].products[0].price' field must be a number."}{ "message": "The '' field is required."}The domain is disabled.
object
Human-readable error. Several validation errors are joined with a space.
Example
{ "message": "Domain is disabled. Please reach out to support@releva.ai to enable it."}Request body larger than 800 KB.
object
Human-readable error. Several validation errors are joined with a space.
Example
{ "message": "request entity too large"}Unexpected server error.
object
Human-readable error. Several validation errors are joined with a space.
Example
{ "message": "An internal error occurred."}