# How events get into Releva

> The three ways events reach Releva, how an event is attached to a profile, what a custom event can carry, when it becomes visible and where it is used.

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.

## Three ways in

| 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](https://releva.ai/documentation/guides/events/check-that-an-event-reached-releva/).

## An event belongs to a profile

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.

## What a custom event carries

| 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](https://releva.ai/documentation/reference/events/overview/).

## Writes are asynchronous

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.

## Where events are used

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

## Next steps

* [Events API overview](https://releva.ai/documentation/reference/events/overview/): Get auth, limits, errors and a working request for every event endpoint.
* [Check that an event reached Releva](https://releva.ai/documentation/guides/events/check-that-an-event-reached-releva/): Confirm that an event you sent was stored with the right data.
* [Export events to a file](https://releva.ai/documentation/guides/events/export-events/): Filter events and receive them in a file by email.
* [See all events of a customer](https://releva.ai/documentation/guides/events/see-all-events-of-a-customer/): Open a profile to see every event Releva tracked for that customer.