# Send custom events

> POST /api/v0/events: record events from your backend on a customer's profile, with the field table, a working curl, responses, errors and limits.

`POST /api/v0/events` records events that happen outside the browser on the profile of a known customer.

## When to use it

Use it when the action happens in your backend (POS, CRM, back office, quote forms, loyalty) or when you want to attach it to a customer by email, phone number or your own profile id. Actions in the browser are easier to send with [Send events from the browser](https://releva.ai/documentation/reference/events/send-events-from-the-browser/), which also works for anonymous visitors.

Order status updates use this endpoint too, with the action `orderStatusChanged`: see [Send order status updates](https://releva.ai/documentation/reference/orders/send-order-status-updates/). Paid orders and refunds have their own calls: [Report paid orders](https://releva.ai/documentation/reference/orders/report-paid-orders/) and [Report refunds](https://releva.ai/documentation/reference/orders/report-refunds/).

## Authentication

Send your shop’s **Secret Key** as a bearer token: `authorization: Bearer $RELEVA_SECRET_KEY`. Never use it in a browser or an app. 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 error messages are in [Events API: Authentication](https://releva.ai/documentation/reference/events/overview/#authentication).

## Request

`POST https://releva.ai/api/v0/events` with `content-type: application/json` and a body `{ "events": [ ... ] }` that holds at least one event. An event is validated strictly: a key that is not in this table or in [Advanced fields](https://releva.ai/documentation/reference/events/send-custom-events/#advanced-fields) is rejected.

| Field         | Type             | Required                  | Notes                                                                                                                                      |
| ------------- | ---------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `profileId`   | string           | at least one of the three | Your customer id. It must be consistent with the `profile.id` you send in the front-end integration.                                       |
| `email`       | string           |                           | The customer’s email address. Either this, `profileId` or `phoneNumber`.                                                                   |
| `phoneNumber` | string           |                           | `+` followed by the international code and digits, for example `+15555550199`. Either this, `profileId` or `email`.                        |
| `action`      | string           | yes                       | The event name, for example `giftCardRedeemed`.                                                                                            |
| `companyId`   | string           | no                        | The B2B company.                                                                                                                           |
| `locale`      | string           | no                        | ISO-639-1 code (`en`). Default: your shop’s language.                                                                                      |
| `timestamp`   | string           | no                        | ISO-8601 with seconds and a zone, for example `2026-10-21T09:15:00Z`. Default: now.                                                        |
| `tags`        | array of strings | no                        |                                                                                                                                            |
| `orderId`     | string           | no                        | The order the event belongs to. If the cart is not checked out, do not set it.                                                             |
| `value`       | number           | no                        | The event’s revenue, converted from `currency` to your shop’s currency.                                                                    |
| `currency`    | string           | no                        | ISO-4217 code (`EUR`).                                                                                                                     |
| `products`    | array of objects | no                        | Each: `id` (required), `variantId`, `quantity`, `price`, `currency`, `custom`. No other key; the name and the rest come from your catalog. |
| `custom`      | object           | no                        | `string`, `numeric` and `date` lists of `{ key, values }`, the same shape as on products.                                                  |

```plaintext
curl -X POST 'https://releva.ai/api/v0/events' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "events": [
      {
        "action": "giftCardRedeemed",
        "email": "maria@example.com",
        "locale": "en",
        "timestamp": "2026-10-21T09:15:00Z",
        "value": 25,
        "currency": "EUR",
        "products": [{ "id": "DEMO-1001" }],
        "custom": {
          "string": [{ "key": "cardType", "values": ["digital"] }]
        }
      },
      {
        "action": "productReviewed",
        "phoneNumber": "+15555550199",
        "locale": "en",
        "timestamp": "2026-10-21T10:30:00Z",
        "products": [
          {
            "id": "DEMO-1001",
            "custom": {
              "string": [{ "key": "rating", "values": ["5"] }]
            }
          }
        ]
      }
    ]
  }'
```

Behaviour to know:

* Any one identifier is enough. Send `profileId` when you have it, matching your front-end integration. Send phone numbers in the international form; a national number is converted with your shop’s country code.
* Entries with no identifier are **dropped without an error** when another entry in the batch is valid. Only when no entry is left does the call fail.
* Without `value`, Releva sums `products[].price × quantity`, or uses the fixed value configured for that action in your conversion mapping.
* Sending an event again stores it again.

### Advanced fields

These fields are not part of a normal event. Leave them out unless you need them.

| Field                   | Type             | Required | Notes                                                                                                                                          |
| ----------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `mergeProfileIds`       | array of strings | no       | Other profile ids to merge into this customer’s profile. A merge cannot be undone; send it only when you are sure the ids are the same person. |
| `firstName`, `lastName` | string           | no       | Sent to connected ad platforms only. Send the shopper’s values.                                                                                |
| `address`               | object           | no       | `city`, `region`, `postalCode`, `country`. Sent to connected ad platforms only.                                                                |
| `url`                   | string           | no       | Max 2048 characters. Sent to connected ad platforms only.                                                                                      |
| `userAgent`             | string           | no       | Max 1024 characters. Sent to connected ad platforms only. The shopper’s browser user agent, never your server’s.                               |
| `ip`                    | string           | no       | Max 45 characters. Sent to connected ad platforms only. The shopper’s IP address, never your server’s. Leave it out if you do not have it.     |

* When several events share the same identifiers, only the first one’s `mergeProfileIds` is used.
* `firstName`, `lastName`, `address`, `url`, `userAgent` and `ip` go to connected ad platforms only. They are not stored on the event or the profile.

## Response

`202 Accepted` with the body `{}`. Events are usually readable within seconds, under **Data Platform › Events** or with [Read events](https://releva.ai/documentation/reference/events/read-events/).

## Errors

Errors have one shape, `{ "message": "..." }`. When several fields fail, the messages are joined with a space.

| Status | When                                 | Message                                                                                                                                                                                                                                    |
| ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Authentication failed                | See [Events API: Authentication](https://releva.ai/documentation/reference/events/overview/#authentication)                                                                                                                                                 |
| `400`  | No identifier in any entry           | `events[0]: at least one of ('profileId', 'email' or 'phoneNumber') is required!`                                                                                                                                                          |
| `400`  | Empty `events`                       | `The 'events' field must contain at least 1 items.`                                                                                                                                                                                        |
| `400`  | Missing `action`                     | `The 'events[0].action' field is required.`                                                                                                                                                                                                |
| `400`  | Unknown key `color`                  | `The object 'events[0]' contains forbidden keys: 'color'.`                                                                                                                                                                                 |
| `400`  | `products[0].name`                   | `The object 'events[0].products[0]' contains forbidden keys: 'name'.`                                                                                                                                                                      |
| `400`  | `timestamp: "2026-10-21"`            | `events[0].timestamp must be a valid ISO-8601 date including seconds and timezone offset with optional milliseconds such as 2020-01-01T23:59:59.999Z or 2020-01-01T23:59:59.999-0500 or 2020-01-01T23:59:59-0500. Got 2026-10-21 instead.` |
| `400`  | `email: "not-an-email"`              | `The 'events[0].email' field must be a valid e-mail.`                                                                                                                                                                                      |
| `400`  | `phoneNumber: "abc"`                 | `events[0].phoneNumber must be a valid telephone number starting with + and international code, e.g. +1. Got abc instead.`                                                                                                                 |
| `400`  | `locale: "en-US"`                    | `events[0].locale must be a valid ISO-639-1 code! Got en-US instead.`                                                                                                                                                                      |
| `400`  | `currency: "EURO"`                   | `events[0].currency must be a valid ISO-4217 currency code! Got EURO instead.`                                                                                                                                                             |
| `400`  | A number in `custom.string[].values` | `The 'events[0].custom.string[0].values[0]' field must be a string.`                                                                                                                                                                       |
| `402`  | Your shop is disabled                | `Domain is disabled. Please reach out to support@releva.ai to enable it.`                                                                                                                                                                  |
| `413`  | Body larger than 800 KB              | `request entity too large`                                                                                                                                                                                                                 |
| `500`  | Unexpected error; retry later        | `An internal error occurred.`                                                                                                                                                                                                              |

## Limits

* Body size: 800 KB per request. There is no other limit on the number of events.
* Rate limits: none.

## Next steps

* [How events get into Releva](https://releva.ai/documentation/learn/events/how-events-get-into-releva/): Learn how an event is attached to a profile and where it is used.
* [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 has the right data.
* [Read events](https://releva.ai/documentation/reference/events/read-events/): Fetch the events back into your own systems.