Skip to content

Area: Developers

POST

Send custom events

Path
/events
Auth
Secret key · server only
POST
/events
curl --request POST \
--url https://releva.ai/api/v0/events \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "events": [ { "action": "wishlistAdd", "email": "maria@example.com", "locale": "en", "timestamp": "2026-10-21T09:15:00.000Z", "tags": [ "wishlist" ], "products": [ { "id": "DEMO-1001", "custom": { "string": [ { "key": "size", "values": [ "M" ] } ] } } ], "custom": { "string": [ { "key": "source", "values": [ "product-page" ] } ], "numeric": [ { "key": "position", "values": [ 2 ] } ] } } ] }'

Records custom events from your backend. Each event is attached to the profile identified by profileId, email or phoneNumber (at least one); a missing profile is created. Processing is asynchronous: a 202 means the events were queued; they are usually readable within seconds. Entries without any identifier are dropped without an error as long as at least one entry is usable. Products are enriched from the catalog by id. firstName, lastName, address, url, userAgent and ip are forwarded to connected ad platforms (Meta, Google, TikTok) only and are not stored on the event or profile. Re-sending an event stores it again.

Order status updates use this endpoint with the action orderStatusChanged: send the orderId of the paid order, the status as the only entry of tags, and the status details as custom.string keys (state, statusLabel, orderName, trackingNumber, trackingCompany, trackingUrl). When state or the first tag is cancelled or canceled (any case), Releva cancels the order about 2 minutes later: it takes the order’s revenue back out and reverses its loyalty points, unless the order already has a refund. See Send order status updates.

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

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

object
action
required

Event name

string
profileId

Your profile id

string
email
string format: email
phoneNumber

+ followed by 1-31 digits after normalisation. On POST /events, values of 5-15 characters are normalised first: non-digits are removed, a leading 00 becomes +, and a number starting with 0 or without a prefix gets the domain country’s dialling code. A value with no digits is dropped.

string
companyId

B2B company id.

string
locale

ISO-639-1 code. Defaults to the domain locale.

string
/^[a-z]{2}$/
timestamp

ISO-8601 date-time with seconds and a timezone offset (Z, +0300 or +03:00), optional milliseconds.

string
/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?(Z|[+-]\d{2}:?\d{2})$/
tags
Array<string>
orderId

Order id. Purchase-mapped actions update personalization once per orderId.

string
value

Monetary value. Overrides product totals; 0 and negatives are kept.

number
currency

ISO-4217 currency of value. Defaults to the domain currency.

string
/^[A-Z]{3}$/
products
Array<object>
object
id
required

Catalog product id.

string
variantId
string
quantity
number
price
number
currency
string
/^[A-Z]{3}$/
custom

Custom attributes, usable in segments.

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>
custom

Custom attributes, usable in segments.

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>
firstName

Forwarded to ad platforms only.

string
lastName

Forwarded to ad platforms only.

string
mergeProfileIds

Profile ids to merge into this profile. Only the first event per identity is honoured.

Array<string>
address

Forwarded to ad platforms only.

object
city
string
region
string
postalCode
string
country
string
url

Forwarded to ad platforms only; not stored.

string
<= 2048 characters
userAgent

Forwarded to ad platforms only.

string
<= 1024 characters
ip

Forwarded to ad platforms only.

string
<= 45 characters

Examples

A custom event

{
"events": [
{
"action": "wishlistAdd",
"email": "maria@example.com",
"locale": "en",
"timestamp": "2026-10-21T09:15:00.000Z",
"tags": [
"wishlist"
],
"products": [
{
"id": "DEMO-1001",
"custom": {
"string": [
{
"key": "size",
"values": [
"M"
]
}
]
}
}
],
"custom": {
"string": [
{
"key": "source",
"values": [
"product-page"
]
}
],
"numeric": [
{
"key": "position",
"values": [
2
]
}
]
}
}
]
}

Accepted for asynchronous processing.

Media typeapplication/json
object
0

Example

{}

Authentication or validation error.

Media typeapplication/json
object
message
required

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

string

Examples

{
"message": "events[0]: at least one of ('profileId', 'email' or 'phoneNumber') is required!"
}

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."
}