Send custom events
- Path
/events- Auth
- Secret key · server only
const url = 'https://releva.ai/api/v0/events';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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]}]}}]}'};
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/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.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
At least one of profileId, email, phoneNumber is required (checked after validation).
object
Event name
Your profile id
+ 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.
B2B company id.
ISO-639-1 code. Defaults to the domain locale.
ISO-8601 date-time with seconds and a timezone offset (Z, +0300 or +03:00), optional milliseconds.
Order id. Purchase-mapped actions update personalization once per orderId.
Monetary value. Overrides product totals; 0 and negatives are kept.
ISO-4217 currency of value. Defaults to the domain currency.
object
Catalog product id.
Custom attributes, usable in segments.
object
object
object
object
Custom attributes, usable in segments.
object
object
object
object
Forwarded to ad platforms only.
Forwarded to ad platforms only.
Profile ids to merge into this profile. Only the first event per identity is honoured.
Forwarded to ad platforms only.
object
Forwarded to ad platforms only; not stored.
Forwarded to ad platforms only.
Forwarded to ad platforms only.
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 ] } ] } } ]}An order status update (orderStatusChanged)
{ "events": [ { "action": "orderStatusChanged", "orderId": "DEMO-ORDER-1001", "email": "maria@example.com", "timestamp": "2026-11-11T10:15:30.000Z", "tags": [ "shipped" ], "custom": { "string": [ { "key": "state", "values": [ "shipped" ] }, { "key": "statusLabel", "values": [ "On its way to you" ] }, { "key": "orderName", "values": [ "#1001" ] }, { "key": "trackingNumber", "values": [ "DEMO-TRACK-1001" ] }, { "key": "trackingCompany", "values": [ "Demo Courier" ] }, { "key": "trackingUrl", "values": [ "https://demo-store.example.com/track/DEMO-TRACK-1001" ] } ] }, "products": [ { "id": "DEMO-1001", "quantity": 1 } ] } ]}Responses
Section titled “Responses”Accepted for asynchronous processing.
object
Example
{}Authentication or validation error.
object
Human-readable error. Several validation errors are joined with a space.
Examples
{ "message": "events[0]: at least one of ('profileId', 'email' or 'phoneNumber') is required!"}{ "message": "The 'events' field must contain at least 1 items."}{ "message": "The 'events[0].action' field is required."}{ "message": "The object 'events[0]' contains forbidden keys: 'color'."}{ "message": "The object 'events[0].products[0]' contains forbidden keys: 'name'."}{ "message": "events[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-10-21 instead."}{ "message": "The 'events[0].email' field must be a valid e-mail."}{ "message": "events[0].phoneNumber must be a valid telephone number starting with + and international code, e.g. +1. Got abc instead."}{ "message": "events[0].locale must be a valid ISO-639-1 code! Got en-US instead."}{ "message": "events[0].currency must be a valid ISO-4217 currency code! Got EURO instead."}{ "message": "The 'events[0].custom.string[0].values[0]' field must be a string."}{ "message": "Authorization header is missing."}{ "message": "Domain with the provided secret key cannot be found."}{ "message": "The '' field is required."}{ "message": "Unexpected end of JSON input"}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."}