# Send events from the browser

> Custom events with Releva.push and the access token: the event fields, a working example, the raw POST /api/v0/push/{accessToken} call, responses and errors.

Custom events from the browser travel in the `events` array of the page push the JavaScript SDK already makes, `Releva.push()`. Nothing else changes on the page.

## When to use it

Use it when the action happens in the browser: a product added to a comparison, a size guide opened, a video played. It is the easiest way to send events and it works for anonymous visitors. When the action happens in your backend, or you want to attach it to a customer by email or phone number, use [Send custom events](https://releva.ai/documentation/reference/events/send-custom-events/) instead.

## Authentication

The push uses your shop’s public **Access Token**, the key that ships in your page source; never the Secret Key. Find it under **Settings › Shop & Integration** ([Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/)). The SDK sends it in the path, `POST /api/v0/push/{accessToken}`. The error messages are in [Endpoints the Releva SDKs call: Authentication](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#authentication).

## Request

Add an `events` array to the context you already push:

```plaintext
Releva.push(accessToken, {
  page: { /* as usual */ },
  profile: { /* as usual */ },
  cart: { /* as usual */ },
  events: [
    {
      action: 'compareAdd',
      tags: ['compare'],
      products: [{ id: 'DEMO-1001' }],
      timestamp: '2026-10-21T09:15:00Z',
      custom: {
        string: [{ key: 'source', values: ['product-page'] }],
        numeric: [],
        date: []
      }
    }
  ]
}, cb, errorCb, options);
```

When `events` is sent it must hold at least one event.

| Field               | Type             | Required | Notes                                                                                          |
| ------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `action`            | string           | yes      | The event name. You can use it to build segments and trigger campaigns based on custom events. |
| `products`          | array of objects | no       | `id` (required), `variantId`, `price`, `currency`, `quantity`. **No `custom` on products.**    |
| `custom`            | object           | no       | `string`, `numeric` and `date` lists of `{ key, values }`.                                     |
| `value`, `currency` | number, string   | no       | A monetary value for the event. Derived from the products when left out.                       |
| `tags`              | array of strings | no       | Default: the page’s tags. You can use them to build segments and trigger campaigns.            |
| `timestamp`         | string           | no       | ISO-8601 with seconds and a zone. Default: now.                                                |
| `locale`            | string           | no       | Accepted, but replaced by `page.locale`.                                                       |
| `orderId`           | string           | no       | For events that belong to an order.                                                            |
| `eventId`           | string           | no       | A deduplication id passed to Meta and TikTok. Not stored.                                      |

Behaviour to know:

* The event belongs to the visitor who pushes it, so there are no identifier fields: `email` on an event is rejected.
* Events are stored only when the push carries a device id, which the SDK always sends. The stored event also has the page `url`, the visitor’s `ip` and the A/B `groupAssignment`.
* Known issue: when your shop has a Google Tag Manager container connected, the SDK pushes every custom event to the `dataLayer` and reads all three `custom` lists without checking that they exist. Until this is fixed, send `custom` with all three lists, even empty ones, as in the example.

The raw call, without the SDK. It also records a page view, so do not run it in a loop:

```plaintext
curl -X POST "https://releva.ai/api/v0/push/$RELEVA_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "context": {
      "deviceId": "demo-device-1001",
      "cart": { "products": [] },
      "events": [
        {
          "action": "compareAdd",
          "products": [{ "id": "DEMO-1001" }],
          "custom": { "string": [], "numeric": [], "date": [] }
        }
      ]
    }
  }'
```

## Response

`200` with the usual push answer: the product blocks, banners and stories for the page. The callback `cb` receives it. The event is usually readable within seconds under **Data Platform › Events**.

## Errors

The SDK passes errors to `errorCb`. From the raw endpoint, `POST /api/v0/push/{accessToken}`:

| Status | When                                               | Message                                                                                                                           |
| ------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Body without `context`                             | `context is missing from request body`                                                                                            |
| `400`  | `email` on an event                                | `The object 'events[0]' contains forbidden keys: 'email'.`                                                                        |
| `400`  | `custom` on an event’s product                     | `The object 'events[0].products[0]' contains forbidden keys: 'custom'.`                                                           |
| `400`  | `events: []`                                       | `The 'events' field must contain at least 1 items.`                                                                               |
| `400`  | Access token problems                              | See [Endpoints the Releva SDKs call: Authentication](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#authentication) |
| `402`  | Your shop is disabled, or value delivery is paused | See [Endpoints the Releva SDKs call: Authentication](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#authentication) |

## Limits

* Body size: 800 KB for a JSON body. The SDK sends a form body, which is limited to 2048 KB.
* Rate limits: none.

## Next steps

* [JavaScript SDK reference](https://releva.ai/documentation/integrations/custom-website/javascript-sdk-reference/): See every field of the push context, including `events`.
* [Check that an event reached Releva](https://releva.ai/documentation/guides/events/check-that-an-event-reached-releva/): Read the stored event in the admin to confirm it arrived.
* [How events get into Releva](https://releva.ai/documentation/learn/events/how-events-get-into-releva/): Learn how browser and server events end up on the same profile.