Events API overview
Used byCustom website, JavaScript SDK, Shopify, WooCommerce, React Native
The events API records and reads the events of one shop. Each call has its own page:
| Call | Endpoint | What it does |
|---|---|---|
| Send custom events | POST /events |
Record events from your backend on a known customer |
| Send search events | POST /search |
Record searches and filtered listings from your backend |
| Read events | GET /events |
Read the shop’s events, newest first, 10 per page |
| Send events from the browser | Releva.push(…, { events: [...] }) |
Record events in the browser with the access token (POST /push/{accessToken}) |
The three server endpoints are under https://releva.ai/api/v0 and use your secret key. Order status updates are orderStatusChanged events on POST /events: see Send order status updates. For how these fit together, read How events get into Releva.
When to use which
Section titled “When to use which”- Send custom events: the action happens outside the browser (POS, CRM, back office, quote forms, loyalty) or you want to attach it to a known customer by email, phone or your profile id.
- Send search events: a search or filtered listing ran on your backend and you want it in the shopper’s history. Searches on your site are tracked by the SDK with
page.queryandpage.filter. - Send events from the browser: the action happens in the browser. Easiest to add, and it works for anonymous visitors.
- Read events: you want the log in your own systems.
Authentication
Section titled “Authentication”Send your shop’s secret key as a bearer token:
authorization: Bearer $RELEVA_SECRET_KEYThe key is a UUID and identifies the shop (domain). Find it in the Releva admin under Settings › Shop & Integration. The SDK path uses the public access token in the URL instead and needs no header.
Authentication failures answer 400, not 401:
| Problem | Message |
|---|---|
No authorization header |
Authorization header is missing. |
Header is not Bearer <token> |
Authorization header is malformed. It should look like `Bearer <string>`. |
| Token is not a UUID | Authorization header contains an invalid Bearer token. |
| No shop has this key | Domain with the provided secret key cannot be found. |
A shop that has been switched off answers 402 with Domain is disabled. Please reach out to support@releva.ai to enable it.
Request format
Section titled “Request format”- HTTPS only. Plain HTTP answers
400 {"message":"We do not support non-HTTPS requests."}. - Send JSON with
content-type: application/json. With any other content type the body is not parsed and you get400 {"message":"The '' field is required."}. - Bodies are limited to 800 KB. Larger bodies answer
413 {"message":"request entity too large"}. There is no maximum number of events per request other than that limit. - Objects are validated strictly: a key that is not in the schema is rejected with
The object 'events[0]' contains forbidden keys: '<key>'. - Timestamps are ISO-8601 with seconds and a zone:
2026-10-21T09:15:00Z,2026-10-21T09:15:00.000Zor2026-10-21T12:15:00+0300. A date without time is rejected. Values are stored in UTC. localeis a two-letter ISO-639-1 code (en, noten-US).currencyis an ISO-4217 code (EUR).- Custom fields use one shape everywhere:
"custom": { "string": [{ "key", "values": [..] }], "numeric": [..], "date": [..] }. Each list is optional; value types must match the list.
Responses
Section titled “Responses”The three write paths answer 202 Accepted with the body {} (the SDK push answers 200 with its normal personalization payload). Processing is asynchronous; events are usually readable within seconds. See Writes are asynchronous.
Errors have one shape, with no code or field property:
{ "message": "The 'events[0].action' field is required." }| Status | When |
|---|---|
202 / 200 |
Accepted and queued |
400 |
Authentication failed, validation failed, or the body could not be parsed |
402 |
The shop is disabled |
413 |
Body larger than 800 KB |
500 |
Unexpected error: {"message":"An internal error occurred."}. Retry later. |
Limits
Section titled “Limits”- Body size: 800 KB per request.
- Rate limits: none on the events endpoints.
GET /eventsreturns at most 10 events per call.POST /searchstores at most the first 10 products of each event.
Versioning
Section titled “Versioning”All events endpoints are under /api/v0. Changes are listed in the API changelog. Unknown fields are rejected, so new fields are safe to add only after they appear in the reference.