Skip to content

Area: Developers

Report paid orders

POST /api/v0/carts reports paid orders. Releva records each order once, on the customer’s profile, and counts it in revenue, attribution and order-based segments.

Call it for every paid order, unless a Releva plugin or connector already does it for your platform. Without it, store revenue, attribution and order-based segmentation do not work. Send it from your server when the payment is confirmed.

Refunds and order statuses have their own calls: Report refunds and Send order status updates.

Send your shop’s Secret Key as a bearer token: authorization: Bearer $RELEVA_SECRET_KEY. Never use it in a browser or an app. Find it under Settings › Shop & Integration (Find your Access Token and Secret Key). The error messages are in Orders and refunds API: Authentication.

POST https://releva.ai/api/v0/carts with content-type: application/json and a body { "carts": [ ... ] } that holds at least one cart. A cart is validated strictly: a key that is not in this table is rejected.

Field Type Required Notes
orderId string yes Your order id. Recorded once per shop; keep it under 255 characters.
cartPaid boolean yes Send true. This endpoint reports paid orders: a cart sent with false records no order, no revenue and no event. Use the JavaScript SDK for carts that have not been paid for.
products array of objects yes The order lines; may be empty. See below.
email, phoneNumber, profileId string at least one Who placed the order. See Identifying the shopper. phoneNumber must start with + followed by digits, for example +49875345976.
timestamp string no When the order was paid. ISO-8601 with seconds and a zone (Z, +0200 or +02:00). Default: now.
companyId string no The B2B company.
mergeProfileIds array of strings no Ids of other profiles to merge into this shopper’s profile, typically the anonymous id a guest browsed under before checking out.
acceptPrivacyPolicy boolean no The shopper’s consent to your privacy policy. When true, the consent is recorded on the shopper’s profile.
custom object no string, numeric and date lists of { key, values }, for example the reward points gained for this order or the order’s city. Send orderName (the order number the customer sees, for example #1001) as a string field when it differs from orderId.
ip string no The shopper’s IP address, forwarded from the storefront session, max 45 characters. Do not send your server’s IP address. See Improving ad platform attribution.
userAgent string no The shopper’s browser user agent, forwarded from the storefront session, max 1024 characters. Do not send your HTTP client’s user agent.
url string no The storefront URL the order was completed on, max 2048 characters. Lets ad platforms record the purchase as a website conversion rather than an offline one.
address object no city and region (max 128 characters each), postalCode and country (max 32 each). Use codes, not names, for region and country. For ad-platform matching.
eventId string no Max 200 characters. The id your browser pixel used for the same purchase, so Meta and TikTok de-duplicate it. Not stored.
group integer no 0 to 9999: the A/B test bucket of the browser the shopper bought in (the SDK’s rlv_g cookie). Send it only as the unchanged cookie value; otherwise leave it out.

Each product:

Field Type Required Notes
price number yes The unit price at which the product was purchased. Revenue is price × quantity, summed over the lines.
quantity integer yes The units purchased.
id string no The same id you send to Create or update products, including the locale and market suffix if your catalog uses one.
variantId string no The purchased variant, when id identifies the product rather than the variant. Recorded for variant-level reporting.
currency string no ISO-4217 code. Leave it out only when the price is already in your shop’s currency.
custom object no string, numeric and date lists of { key, values }, for example the chosen size and color.

Releva looks each line up in your catalog by id and copies the product’s name, categories and custom fields onto the order. That is what makes segments such as “bought in category X in the last 30 days” work. A line whose id matches nothing in the catalog still counts towards revenue, but carries no product attributes.

curl -X POST 'https://releva.ai/api/v0/carts' \
-H "authorization: Bearer $RELEVA_SECRET_KEY" \
-H 'content-type: application/json' \
-d '{
"carts": [
{
"orderId": "DEMO-ORDER-1001",
"cartPaid": true,
"email": "maria@example.com",
"phoneNumber": "+15555550199",
"timestamp": "2026-03-27T14:05:00.000Z",
"products": [
{
"id": "DEMO-1001",
"variantId": "DEMO-1001-M",
"price": 39.9,
"currency": "EUR",
"quantity": 1,
"custom": {
"string": [{ "key": "color", "values": ["white"] }],
"numeric": [{ "key": "size", "values": [40] }]
}
},
{ "id": "DEMO-1002", "price": 19.2, "currency": "EUR", "quantity": 2 }
],
"custom": {
"string": [{ "key": "city", "values": ["Sofia"] }],
"numeric": [{ "key": "rewardPoints", "values": [18] }]
}
}
]
}'

Every cart needs at least one of email, phoneNumber or profileId: this is how the order is attached to a profile. Send as many of them as you have; Releva resolves them to a single profile.

  • email and phoneNumber: the shopper’s contact details as they appear on the order. Send phone numbers in international format, + followed by digits.
  • profileId: your own customer id, if you have one. Use it consistently across the Profile APIs and this one, and orders are attached to the right profile even for shoppers who change their email address.
  • mergeProfileIds: on a guest checkout, pass the anonymous id the shopper browsed under, so their pre-purchase browsing history and campaign attribution follow them onto the identified profile.

An orderId is recorded once per shop. If the same order reaches Releva twice (a webhook redelivery, a retry after a timeout, a backfill that overlaps live traffic), only the first one counts, so repeating a call never double-counts revenue. The flip side: a mistake cannot be corrected by sending the same orderId again; contact support if an order needs changing. A repeat can only add cart-level custom keys the stored order is missing, such as a late orderName. Use the order identifier your own systems use: support, refunds and order-level reports match on it.

Orders reported from your backend carry none of the browser context that ad platforms use to match a purchase to an ad click. Forward what you have, and the purchase events Releva sends to Meta, Google and TikTok get better match quality:

curl -X POST 'https://releva.ai/api/v0/carts' \
-H "authorization: Bearer $RELEVA_SECRET_KEY" \
-H 'content-type: application/json' \
-d '{
"carts": [
{
"orderId": "DEMO-ORDER-1002",
"cartPaid": true,
"email": "maria@example.com",
"timestamp": "2026-03-27T14:05:00.000Z",
"ip": "203.0.113.24",
"userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1",
"url": "https://demo-store.example.com/checkout/thank-you",
"address": { "city": "Sofia", "region": "23", "postalCode": "1000", "country": "BG" },
"eventId": "b7f3c1e2-4a5d-4f0a-9c3e-1d2b3a4c5d6e",
"products": [{ "id": "DEMO-1001", "price": 39.9, "currency": "EUR", "quantity": 1 }]
}
]
}'

Send the shopper’s values, not your server’s: ip and userAgent are the ones the shopper was browsing with (most platforms let you keep them on the cart or session during checkout), and url is the storefront page the order was completed on. Leave out any you cannot supply: no value is better than your data center’s IP address or your HTTP client’s user agent, which would be matched as if they were the customer’s.

202 Accepted with the body {}. The orders are live within about a minute. A 202 means the request was valid and queued, not that the order was recorded:

  • Orders are held for about 30 seconds before they are recorded, so a browser report of the same order can add its session details.
  • A repeated orderId answers 202 and is dropped. It adds only cart-level custom keys the stored order does not have yet; nothing else from it is recorded.
  • A cart with no email, phoneNumber or profileId is dropped without an error when another cart in the request is valid.

Errors have one shape, { "message": "..." }. When several fields fail, the messages are joined with a space.

Status When Message
400 Authentication failed See Orders and refunds API: Authentication
400 Empty carts The 'carts' field must contain at least 1 items.
400 Missing orderId The 'carts[0].orderId' field is required.
400 Numeric orderId The 'carts[0].orderId' field must be a string.
400 Missing cartPaid The 'carts[0].cartPaid' field is required.
400 cartPaid: "yes" The 'carts[0].cartPaid' field must be a boolean.
400 Missing products The 'carts[0].products' field is required.
400 No email, phoneNumber or profileId on any cart For each cart, at least one of (email, phoneNumber, profileId) is required!
400 email: "maria.example.com" The 'carts[0].email' field must be a valid e-mail.
400 timestamp: "2026-03-27" 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.
400 Unknown key total on the cart The object 'carts[0]' contains forbidden keys: 'total'.
400 Unknown key street in address The object 'carts[0].address' contains forbidden keys: 'street'.
400 ip longer than 45 characters The 'carts[0].ip' field length must be less than or equal to 45 characters long.
400 currency: "EURO" carts[0].products[0].currency must be a valid ISO-4217 currency code! Got EURO instead.
400 price: "39.90" (a string) The 'carts[0].products[0].price' field must be a number.
400 Missing quantity The 'carts[0].products[0].quantity' field is required.
402 Your shop is disabled Domain is disabled. Please reach out to support@releva.ai to enable it.
413 Body larger than 800 KB request entity too large
500 Unexpected error; retry later An internal error occurred.

A null cart in the array answers 500 instead of 400. Do not send one.

  • Body size: 800 KB per request. Send backfills in batches.
  • Rate limits: none.
  • Processing: each order is recorded about 30 seconds after the call.