Skip to content

Area: Developers

POST

Report paid orders

Path
/carts
Auth
Secret key · server only
POST
/carts
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.

Media typeapplication/json
object
carts
required
Array<object>
>= 1 items

At least one of email, phoneNumber or profileId is required (checked after schema validation).

object
orderId
required

Your order id. Recorded once per domain; repeats are ignored. The length limit is enforced by storage, not by validation.

string
<= 255 characters
cartPaid
required

Send true. false records no order and no revenue.

boolean
email

Shopper’s email. null is treated as absent.

string | null format: email
phoneNumber

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.

string | null
/^\+\d{1,31}$/
profileId

Your own customer id.

string
mergeProfileIds

Profiles to merge into this shopper’s profile, such as the anonymous id of a guest checkout.

Array<string>
timestamp

Order time with seconds and a timezone offset. Defaults to the time of the request.

string format: date-time
/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?(Z|[+-]\d{2}:?\d{2})$/
companyId

B2B company id.

string
custom
object
string
Array<object>
object
key
required
string
values
required
Array<string>
numeric
Array<object>
object
key
required
string
values
required
Array<number>
date
Array<object>
object
key
required
string
values
required
Array<string>
acceptPrivacyPolicy

true records privacy policy consent on the profile.

boolean
userAgent

The shopper’s browser user agent (not your server’s). Used for ad-platform matching.

string
<= 1024 characters
ip

The shopper’s IP address (not your server’s). Used for ad-platform matching.

string
<= 45 characters
url

Storefront URL the order was completed on.

string
<= 2048 characters
address

Order address for ad-platform advanced matching.

object
city
string
<= 128 characters
region

Region code

string
<= 128 characters
postalCode
string
<= 32 characters
country

ISO-3166-1 alpha-2 code, such as BG.

string
<= 32 characters
eventId

Deduplication id shared with your browser pixel, forwarded to ad platforms.

string
<= 200 characters
products
required
Array<object>
0
object
id

Catalog product id (as sent to POST /products). Used to copy product attributes onto the order.

string
variantId

Purchased variant id.

string
price
required

Unit price. Must be a JSON number.

number
quantity
required

Units purchased.

number
currency

ISO-4217 code. Omit only when the price is in the domain currency.

string
/^[A-Z]{3}$/
custom
object
string
Array<object>
object
key
required
string
values
required
Array<string>
numeric
Array<object>
object
key
required
string
values
required
Array<number>
date
Array<object>
object
key
required
string
values
required
Array<string>

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
}
]
}
]
}

Accepted for asynchronous processing.

Media typeapplication/json
object
0

Example

{}

Authentication or validation error, or no cart carries an identifier.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Examples

{
"message": "Authorization header is missing."
}

The domain is disabled.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "Domain is disabled. Please reach out to support@releva.ai to enable it."
}

Request body larger than 800 KB.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "request entity too large"
}

Unexpected server error.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "An internal error occurred."
}