Send custom events
POST /api/v0/events records events that happen outside the browser on the profile of a known customer.
When to use it
Section titled “When to use it”Use it when the action happens in your backend (POS, CRM, back office, quote forms, loyalty) or when you want to attach it to a customer by email, phone number or your own profile id. Actions in the browser are easier to send with Send events from the browser, which also works for anonymous visitors.
Order status updates use this endpoint too, with the action orderStatusChanged: see Send order status updates. Paid orders and refunds have their own calls: Report paid orders and Report refunds.
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 Events API: Authentication.
Request
Section titled “Request”POST https://releva.ai/api/v0/events with content-type: application/json and a body { "events": [ ... ] } that holds at least one event. An event is validated strictly: a key that is not in this table or in Advanced fields is rejected.
| Field | Type | Required | Notes |
|---|---|---|---|
profileId |
string | at least one of the three | Your customer id. It must be consistent with the profile.id you send in the front-end integration. |
email |
string | The customer’s email address. Either this, profileId or phoneNumber. |
|
phoneNumber |
string | + followed by the international code and digits, for example +15555550199. Either this, profileId or email. |
|
action |
string | yes | The event name, for example giftCardRedeemed. |
companyId |
string | no | The B2B company. |
locale |
string | no | ISO-639-1 code (en). Default: your shop’s language. |
timestamp |
string | no | ISO-8601 with seconds and a zone, for example 2026-10-21T09:15:00Z. Default: now. |
tags |
array of strings | no | |
orderId |
string | no | The order the event belongs to. If the cart is not checked out, do not set it. |
value |
number | no | The event’s revenue, converted from currency to your shop’s currency. |
currency |
string | no | ISO-4217 code (EUR). |
products |
array of objects | no | Each: id (required), variantId, quantity, price, currency, custom. No other key; the name and the rest come from your catalog. |
custom |
object | no | string, numeric and date lists of { key, values }, the same shape as on products. |
curl -X POST 'https://releva.ai/api/v0/events' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json' \ -d '{ "events": [ { "action": "giftCardRedeemed", "email": "maria@example.com", "locale": "en", "timestamp": "2026-10-21T09:15:00Z", "value": 25, "currency": "EUR", "products": [{ "id": "DEMO-1001" }], "custom": { "string": [{ "key": "cardType", "values": ["digital"] }] } }, { "action": "productReviewed", "phoneNumber": "+15555550199", "locale": "en", "timestamp": "2026-10-21T10:30:00Z", "products": [ { "id": "DEMO-1001", "custom": { "string": [{ "key": "rating", "values": ["5"] }] } } ] } ] }'Behaviour to know:
- Any one identifier is enough. Send
profileIdwhen you have it, matching your front-end integration. Send phone numbers in the international form; a national number is converted with your shop’s country code. - Entries with no identifier are dropped without an error when another entry in the batch is valid. Only when no entry is left does the call fail.
- Without
value, Releva sumsproducts[].price × quantity, or uses the fixed value configured for that action in your conversion mapping. - Sending an event again stores it again.
Advanced fields
Section titled “Advanced fields”These fields are not part of a normal event. Leave them out unless you need them.
| Field | Type | Required | Notes |
|---|---|---|---|
mergeProfileIds |
array of strings | no | Other profile ids to merge into this customer’s profile. A merge cannot be undone; send it only when you are sure the ids are the same person. |
firstName, lastName |
string | no | Sent to connected ad platforms only. Send the shopper’s values. |
address |
object | no | city, region, postalCode, country. Sent to connected ad platforms only. |
url |
string | no | Max 2048 characters. Sent to connected ad platforms only. |
userAgent |
string | no | Max 1024 characters. Sent to connected ad platforms only. The shopper’s browser user agent, never your server’s. |
ip |
string | no | Max 45 characters. Sent to connected ad platforms only. The shopper’s IP address, never your server’s. Leave it out if you do not have it. |
- When several events share the same identifiers, only the first one’s
mergeProfileIdsis used. firstName,lastName,address,url,userAgentandipgo to connected ad platforms only. They are not stored on the event or the profile.
Response
Section titled “Response”202 Accepted with the body {}. Events are usually readable within seconds, under Data Platform › Events or with Read events.
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 Events API: Authentication |
400 |
No identifier in any entry | events[0]: at least one of ('profileId', 'email' or 'phoneNumber') is required! |
400 |
Empty events |
The 'events' field must contain at least 1 items. |
400 |
Missing action |
The 'events[0].action' field is required. |
400 |
Unknown key color |
The object 'events[0]' contains forbidden keys: 'color'. |
400 |
products[0].name |
The object 'events[0].products[0]' contains forbidden keys: 'name'. |
400 |
timestamp: "2026-10-21" |
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. |
400 |
email: "not-an-email" |
The 'events[0].email' field must be a valid e-mail. |
400 |
phoneNumber: "abc" |
events[0].phoneNumber must be a valid telephone number starting with + and international code, e.g. +1. Got abc instead. |
400 |
locale: "en-US" |
events[0].locale must be a valid ISO-639-1 code! Got en-US instead. |
400 |
currency: "EURO" |
events[0].currency must be a valid ISO-4217 currency code! Got EURO instead. |
400 |
A number in custom.string[].values |
The 'events[0].custom.string[0].values[0]' field must be a string. |
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. |
Limits
Section titled “Limits”- Body size: 800 KB per request. There is no other limit on the number of events.
- Rate limits: none.