Skip to content

Area: Developers

Send custom events

POST /api/v0/events records events that happen outside the browser on the profile of a known customer.

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.

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.

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 profileId when 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 sums products[].price × quantity, or uses the fixed value configured for that action in your conversion mapping.
  • Sending an event again stores it again.

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 mergeProfileIds is used.
  • firstName, lastName, address, url, userAgent and ip go to connected ad platforms only. They are not stored on the event or the profile.

202 Accepted with the body {}. Events are usually readable within seconds, under Data Platform › Events or with Read events.

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.
  • Body size: 800 KB per request. There is no other limit on the number of events.
  • Rate limits: none.