Skip to content

Area: Developers

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.

  • 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.query and page.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.

Send your shop’s secret key as a bearer token:

authorization: Bearer $RELEVA_SECRET_KEY

The 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.

  • 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 get 400 {"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.000Z or 2026-10-21T12:15:00+0300. A date without time is rejected. Values are stored in UTC.
  • locale is a two-letter ISO-639-1 code (en, not en-US). currency is 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.

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.
  • Body size: 800 KB per request.
  • Rate limits: none on the events endpoints.
  • GET /events returns at most 10 events per call.
  • POST /search stores at most the first 10 products of each event.

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.