Skip to content

Area: Developers

How events get into Releva

Releva keeps one event log per shop (domain). Segments, campaign triggers, profile timelines, analytics and ad-platform conversions all read from it. This page explains how events get there, what a custom event can carry and what happens after you send one.

Method Who drives it Best for
JavaScript SDK (Releva.push) Your site. Every push reports the page, the visitor’s cart and profile; add an events array for custom events such as “added to compare”. Anything that happens in the browser, including for anonymous visitors.
Platform connector (Shopify, WooCommerce, Magento and others) Releva. The connector sends orders, refunds and subscription changes. Shops on a supported platform. No code.
Events API (POST /api/v0/events, POST /api/v0/search) You call it from your backend when something happens outside the browser: a store visit, a quote request, a loyalty action, a server-side search. Known customers and back-office systems.

You can combine them. Everything lands in the same log, which the admin shows under Data Platform › Events: see Check that an event reached Releva.

Every stored event has a profile. How the profile is found depends on the way in:

  • SDK events belong to the visitor who pushed them: the device, and the profile once the visitor identifies (logs in, subscribes, orders). You do not send an identifier on the event. Without a device id Releva accepts the push but stores nothing; the SDK always sends one.
  • API events need one of profileId (your customer id, the same one your frontend integration sends), email or phoneNumber. Releva finds the profile with that identity or creates it. A phone number without a + is completed with your shop’s country code. In a batch, entries without any identifier are dropped without an error as long as one entry is usable; the call still answers 202.
  • Search events sent through the API accept email only.

The admin shows the profile’s name, e-mail or phone in the Profile column and links to the profile’s own event list. If the profile is later deleted or merged, the event stays in the log without a link.

Part Notes
action The event name, free text, case-sensitive. It becomes the event type everywhere: the admin filter lists it as Custom Event: <action>, segments and GET /events filter on it.
timestamp When it happened, ISO-8601 with seconds and offset, for example 2026-10-21T09:15:00Z. Stored in UTC. Defaults to the time Releva received it.
products The products involved, by id. Releva fills in name, price, SKU, categories and custom fields from your catalog. An id that is not in the catalog is stored as sent, and the admin shows the product id instead of a name.
custom Your own attributes: string, numeric and date lists of { key, values }. They are shown under Raw Data, can be exported as columns and are usable in segments.
value and currency The money value of the event. If you leave value out, Releva sums the product prices. The value is converted to your shop’s currency.
tags, orderId, companyId Stored on the event. orderId also stops a purchase conversion from being counted twice.

Fields such as firstName, lastName, address, url, userAgent and ip on POST /events exist for ad-platform matching only. They are forwarded to Meta, Google and TikTok when those accounts are connected and are not stored on the event or the profile.

Field-by-field rules, limits and error messages are in the Events API overview.

The events endpoints answer 202 Accepted with {} as soon as the request is valid and queued. The event is written a few seconds later. Because of that:

  • A 202 means the payload was valid, not that the event is stored. Check the Events page or GET /api/v0/events.
  • Validation errors are synchronous and come back as 400 with a message.
  • Sending the same event twice stores it twice. There is no deduplication on the event itself.

A custom action appears in the admin’s Filter by event action… list only after the first event with that name has been stored.

  • Data Platform › Events and each profile’s Recent Events: the raw log, newest first, with an export to file.
  • Segments: behaviour segments match on action, time, products and custom fields.
  • Campaigns and workflows: triggers on events.
  • Personalization: actions you map to a purchase, add-to-cart or cart-create conversion in your analytics settings also update the shopper’s recommendation context.
  • Ad platforms: every API and SDK custom event is also sent as a custom/<action> conversion to Meta, GA4 and TikTok when the accounts are connected.
  • Your systems: GET /api/v0/events returns the log, 10 events per page.