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.
When to use it
Section titled “When to use it”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.
Authentication
Section titled “Authentication”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.
Request
Section titled “Request”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] }] } } ] }'Identifying the shopper
Section titled “Identifying the shopper”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.
emailandphoneNumber: 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.
One order, one record
Section titled “One order, one record”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.
Improving ad platform attribution
Section titled “Improving ad platform attribution”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.
Response
Section titled “Response”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
orderIdanswers202and is dropped. It adds only cart-levelcustomkeys the stored order does not have yet; nothing else from it is recorded. - A cart with no
email,phoneNumberorprofileIdis dropped without an error when another cart in the request is valid.
Errors
Section titled “Errors”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.
Limits
Section titled “Limits”- Body size: 800 KB per request. Send backfills in batches.
- Rate limits: none.
- Processing: each order is recorded about 30 seconds after the call.