> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bevits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom events

> Send Bevits what happens in your system and use those events to start flows.

An event is a fact: this person did this, at this moment, with these details.
Send one `POST` and Bevits stores the event, links it to a customer, and starts
the flows that listen to that name.

```bash theme={null}
curl https://api.bevits.com/v1/events \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "customer": { "email": "ana@exemplo.com.br" },
    "properties": { "tracking_code": "BR123", "carrier": "Correios" }
  }'
```

* **URL:** `POST https://api.bevits.com/v1/events`
* **Format:** `name` (what happened), `customer` (who it happened to), and
  `properties` (details). Optional: `occurred_at`, `external_id`, and
  `backfill`.
* **How it links to the customer:** send the identifiers you have
  (`external_id`, `tax_id`, `email`, `phone`). The first one that matches, in
  that order, decides. If none matches, the customer is created. The response
  says which customer it was and which identifier found it.

Nothing is registered beforehand: not the event, its properties, or the
customer.

> [!NOTE]
>
> The key needs the `write` or `events:write` scope. See
> [Send-only key](#send-only-key).

## Full request

```json theme={null}
{
  "name": "order_shipped",
  "customer": {
    "external_id": "u_8842",
    "email": "ana@exemplo.com.br",
    "phone": "+5511988887777",
    "tax_id": "123.456.789-09",
    "name": "Ana Souza",
    "attributes": { "plano": "premium" }
  },
  "properties": {
    "order_number": "10293",
    "tracking": { "code": "BR123", "carrier": "Correios" },
    "items": [{ "sku": "CAM-01", "name": "Camiseta", "quantity": 2 }]
  },
  "occurred_at": "2026-11-18T14:03:00-03:00",
  "external_id": "ship_10293",
  "backfill": false
}
```

| Field | Required | Rule |
| - | - | - |
| `name` | yes | Lowercase letters, digits, and underscores, starting with a letter (`^[a-z][a-z0-9_]*$`). Up to 64 characters. |
| `customer` | yes | At least one identifier: `id`, `external_id`, `tax_id`, `email`, or `phone`. |
| `properties` | no | Free-form JSON object. See [Properties and limits](#properties-and-limits). |
| `occurred_at` | no | ISO 8601 with offset. Default: the moment the event is received. |
| `external_id` | no | ID of the fact in your system, up to 255 characters. See [Retrying safely](#retrying-safely). |
| `backfill` | no | `true` stores the event without triggering flows. Default `false`. |

Unknown fields are rejected with `unknown_field` instead of being ignored. A
`customerId` in place of `customer.id` fails on the first call.

The name is strict so that `Order Shipped`, `order shipped`, and
`order_shipped` do not become three different events. An invalid name fails on
the first call and suggests the right one:

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "invalid_event_name",
    "message": "Event names use lowercase letters, digits and underscores, start with a letter and have at most 64 characters. Did you mean \"order_shipped\"?",
    "param": "name",
    "suggestion": "order_shipped",
    "request_id": "req_07f6cdc3c20249d6afcd90b4"
  }
}
```

```bash cURL theme={null}
curl https://api.bevits.com/v1/events \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "customer": {
      "external_id": "u_8842",
      "email": "ana@exemplo.com.br",
      "phone": "+5511988887777"
    },
    "properties": {
      "order_number": "10293",
      "tracking": { "code": "BR123", "carrier": "Correios" }
    },
    "occurred_at": "2026-11-18T14:03:00-03:00",
    "external_id": "ship_10293"
  }'
```

```javascript Node.js theme={null}
const response = await fetch("https://api.bevits.com/v1/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BEVITS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "order_shipped",
    customer: {
      external_id: "u_8842",
      email: "ana@exemplo.com.br",
      phone: "+5511988887777",
    },
    properties: {
      order_number: "10293",
      tracking: { code: "BR123", carrier: "Correios" },
    },
    occurred_at: "2026-11-18T14:03:00-03:00",
    external_id: "ship_10293",
  }),
});

const body = await response.json();

if (!response.ok) {
  // error.code names the reason, error.param names the field.
  throw new Error(`${body.error.code ?? body.error.type}: ${body.error.message}`);
}

// 201: new event. 200: the external_id already existed (body.duplicate === true).
console.log(body.id, body.customer, body.flows);
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.bevits.com/v1/events",
    headers={"Authorization": f"Bearer {os.environ['BEVITS_API_KEY']}"},
    json={
        "name": "order_shipped",
        "customer": {
            "external_id": "u_8842",
            "email": "ana@exemplo.com.br",
            "phone": "+5511988887777",
        },
        "properties": {
            "order_number": "10293",
            "tracking": {"code": "BR123", "carrier": "Correios"},
        },
        "occurred_at": "2026-11-18T14:03:00-03:00",
        "external_id": "ship_10293",
    },
    timeout=30,
)
body = response.json()

if not response.ok:
    # error.code names the reason, error.param names the field.
    error = body["error"]
    raise RuntimeError(f"{error.get('code', error['type'])}: {error['message']}")

# 201: new event. 200: the external_id already existed (body["duplicate"] is True).
print(body["id"], body["customer"], body["flows"])
```

## How the event links to the customer

**The rule:** identifiers are tried in this order, `id`, `external_id`,
`tax_id`, `email`, `phone`, and the first one that belongs to an active
customer decides. If none does, the customer is created with everything that
was sent.

| Identifier | What it is | How it is matched |
| - | - | - |
| `id` | Bevits customer ID (`cus_…`) | Exact. |
| `external_id` | The customer's ID in your system | Exact text, up to 255 characters. |
| `tax_id` | CPF or CNPJ (Brazilian tax IDs) | Digits only. Must be a valid document. |
| `email` | Email | Lowercase, with surrounding spaces removed. |
| `phone` | Phone | E.164 (`+5511988887777`). Without a country code, the store's country is assumed. |

`external_id` and `tax_id` are **strong** identifiers: they name one person.
`email` and `phone` are **weak**: they can be shared or change hands. Each
identifier belongs to a single customer, and that is what makes the outcome
predictable.

An event never merges two customers. When something does not line up, the API
keeps what already existed and tells you in `warnings`:

| Situation | What happens | Warning |
| - | - | - |
| No identifier matches | The customer is created with everything that was sent. The response carries `customer.created: true`. | |
| The matched customer does not have one of the identifiers sent | The identifier is stored on that customer. | |
| Several active customers have the same tax ID, email, or phone (older duplicates) | The oldest one matches. The choice is fixed for the next calls. | `ambiguous_identifier` |
| The email or phone belongs to a customer whose `external_id` or `tax_id` differs from the one sent | That identifier is not used to match: it is another person with the same contact. The lookup moves on to the next one. If none matches, a new customer is created. It keeps the contact, but the email or phone still identifies the original owner. | `identifier_conflict` |
| Matched by `id`, `external_id`, or `tax_id`, and the email or phone sent differs from the current one | The contact is replaced. The customer is no longer found by the old value. | |
| Matched by `email` or `phone`, and the other contact sent differs from the current one | The current contact is kept. | `identifier_mismatch` |
| The `external_id` or `tax_id` sent differs from the one the matched customer already has | Nothing is overwritten. | `identifier_mismatch` |
| One of the other identifiers sent belongs to another customer | The event stays with the matched customer. Nothing is moved from one customer to the other. | `identifier_conflict` |
| `customer.id` does not exist | `404` with `customer_not_found`. The other identifiers are not tried. | |
| The identifiers only belong to a deleted customer | A deleted customer never matches and is never reactivated by an event. A new customer is created. | |

Each warning carries `code`, `message`, and `param` (for example
`customer.email`).

### Customer data in the same call

* `customer.name` updates the customer's name.
* `customer.attributes` sets customer attributes. Only the keys sent change.
  Values can be text (up to 256 characters), a number, or a boolean, and keys
  have up to 64 characters.
* An attribute that does not exist yet is created with the type inferred from
  the value: text, number, boolean, or date (ISO 8601 text).
* A value that does not fit the type of an existing attribute rejects the event
  with `attribute_type_mismatch`. Nothing is stored.
* A customer with only an `external_id`, with no email or phone, is valid. The
  event is stored, and a flow that cannot reach that customer through any
  channel shows as `skipped` with `no_contact_channel`.

## Retrying safely

`external_id` is the ID of the fact in your system, such as `ship_10293`. It is
unique per event name for **90 days**. Sending the same `name` and
`external_id` again in that period responds `200` with the original event and
`duplicate: true`.

* **Nothing happens again.** The resend triggers no flows and does not touch
  the customer: attributes and identifiers are not reapplied.
* **Different body on the resend.** The first one stands, and the response
  carries the `payload_mismatch` warning. It is not an upsert.
* **Without `external_id`.** Every call is a new event. The API never
  deduplicates on its own.

The `Idempotency-Key` header is also accepted on the send routes
(`POST /v1/events` and `POST /v1/events/bulk`). For 24 hours, repeating the
same key with the same body returns the stored response, with the
`Idempotent-Replayed: true` header. The same key with another body responds
`409 conflict`.

Use both: `external_id` protects the fact, `Idempotency-Key` protects the
request. In a batch, `Idempotency-Key` is what keeps a timeout from duplicating
the items that have no `external_id`.

```bash theme={null}
curl https://api.bevits.com/v1/events \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-ship-10293" \
  -d '{
    "name": "order_shipped",
    "customer": { "external_id": "u_8842" },
    "external_id": "ship_10293"
  }'
```

## Properties and limits

`properties` is a free-form JSON object and it is entirely yours: there are no
reserved keys. Values can be text, number, boolean, date (ISO 8601 text), list,
and object. There is no schema to register. The type of each property is
inferred from the events received and shows up in [Event types](#event-types).

What does not fit is rejected with `422` and an `error.code`. Nothing is
truncated.

| Limit | Value | `error.code` |
| - | - | - |
| Event size | 64 KB | `event_too_large` |
| Keys in `properties`, counting nested ones | 200 | `too_many_properties` |
| Depth of `properties` | 5 levels | `properties_too_deep` |
| Items per list | 100 | `array_too_long` |
| Active event names per store | 500 | `too_many_event_names` |
| Events per batch | 100 | |
| Batch size | 1 MB | `batch_too_large` |

The limit on names exists to catch early the mistake of putting data in the
name, such as `order_10293_shipped`. The name says what happened; IDs and
values go in `properties`. Archived event types do not count toward the limit,
and an event with an archived name is rejected with `event_type_archived`.

## Time

`occurred_at` says when the fact happened. Without it, the moment the event is
received is used.

| `occurred_at` | Result |
| - | - |
| More than 5 minutes in the future | `422` with `occurred_at_in_future`. |
| Older than 13 months | `422` with `occurred_at_too_old`. |
| Older than 72 hours | The event is stored but triggers no flows: `flows[].reason` is `stale`. |
| Any accepted value, with `backfill: true` | The event is stored but triggers no flows: `flows[].reason` is `backfill`. |

Use `backfill: true` to import history. The 72-hour rule protects against a
reprocessed queue dumping old messages on your customers.

## What the response tells you

`201 Created` when the event is new. `200 OK` with the original event when the
`external_id` already existed.

```json theme={null}
{
  "object": "event",
  "id": "evt_01jd2v9k3m8q4r5s6t7u8v9w0x",
  "name": "order_shipped",
  "external_id": "ship_10293",
  "occurred_at": "2026-11-18T17:03:00.000Z",
  "received_at": "2026-11-18T17:03:01.000Z",
  "customer": {
    "id": "cus_ckabc123",
    "matched_by": "external_id",
    "created": false
  },
  "flows": [
    { "id": "flw_ckdef456", "name": "Pedido enviado", "status": "queued" },
    {
      "id": "flw_ckghi789",
      "name": "Entrega expressa",
      "status": "skipped",
      "reason": "filter_not_matched"
    }
  ],
  "properties": {
    "order_number": "10293",
    "tracking": { "code": "BR123", "carrier": "Correios" }
  },
  "backfill": false,
  "livemode": true
}
```

A success response is a promise: the event is stored, linked to a customer, and
readable by its `id` right away.

* `customer.matched_by` says which identifier found the customer. When the
  event created the customer, `created: true` comes back and `matched_by` is
  omitted.
* `flows` lists the **active** flows that listen to this name. An empty list
  means no flow is listening.
* `warnings` appears only when there is something to warn about. A warning
  never replaces an error.
* `duplicate: true` appears when the call returned an event that already
  existed.

### `flows[].status` and `flows[].reason`

| `status` | Meaning |
| - | - |
| `queued` | The flow start was queued. This is what the send response reports. |
| `started` | The flow was started for the customer. It shows when you read the event later. |
| `skipped` | The flow was not started. `reason` says why. |

| `reason` | When it is decided | Meaning |
| - | - | - |
| `test_mode` | On send | The event was sent with a test key. |
| `backfill` | On send | The event came with `backfill: true`. |
| `stale` | On send | `occurred_at` is more than 72 hours old. |
| `filter_not_matched` | On send | The properties did not pass the trigger filters. |
| `no_contact_channel` | Later | The customer does not have the contact (email or phone) for any channel the flow uses. |
| `no_consent` | Later | The customer has the contact but did not agree to receive messages of this nature on any channel the flow uses ([who receives](#who-receives-the-flows-messages)). |
| `flow_inactive` | Later | The flow was deactivated before it started. |
| `flow_error` | On send or later | The flow has a trigger or steps that cannot be read, so it was not started. Open the flow in Bevits and publish it again. |
| `dispatch_failed` | Later | Bevits could not start the flow, even after retrying for 72 hours. No message was sent for this event. |

To find out what happened to a `queued` flow, [read the event](#reading-an-event).

### Flow warnings

A started flow may carry `flows[].warnings`: what it could not do and you can
fix when sending. The field only appears when there is something to report.

| `flows[].warnings[].code` | Meaning |
| - | - |
| `missing_variable` | A flow message (email, SMS or WhatsApp) was skipped because a template variable had no value and no fallback text. `param` points to the missing property, such as `properties.tracking.code`. |

### Warnings

| `warnings[].code` | Meaning |
| - | - |
| `ambiguous_identifier` | Several customers had the same identifier. The oldest one was used. |
| `identifier_conflict` | An identifier that was sent belongs to another customer and stayed with them. |
| `identifier_mismatch` | The customer already had a different value for that identifier, and it was kept. |
| `payload_mismatch` | An event with the same `name` and `external_id` and another body already existed. The first one stands. |

## Starting a flow with the event

A flow listens to a custom event through the `custom.<event_name>` trigger.
Create the flow with `POST /v1/flows`, using `platform: "custom"` and the event
name in `event`:

```json theme={null}
{
  "name": "Pedido enviado pelos Correios",
  "trigger": {
    "platform": "custom",
    "event": "order_shipped",
    "filters": [
      { "property": "tracking.carrier", "operator": "equals", "value": "Correios" }
    ]
  },
  "start": "notify",
  "nodes": [
    { "key": "notify", "type": "send_whatsapp", "template_id": "wtp_…" }
  ]
}
```

* `trigger.filters` is optional and takes up to 10 filters. The flow starts
  only when all of them match the event's properties. `property` is the path of
  the property, such as `tracking.carrier` or `items[0].sku`.
* A property that is missing or has another type simply does not pass the
  filter. The flow shows as `skipped` with `filter_not_matched`.
* Messages use the event's properties as [variables](#variables), and
  condition nodes compare them with `field: "event.<path>"`
  ([conditions](#conditions)).
* The flow is created as a draft. It only receives events after it is activated
  (`POST /v1/flows/{flow_id}/activate`).
* The flow can be created before the first event with that name arrives.

In the dashboard, the same trigger is **Events API → Custom event**, in the
flow's trigger block: pick an event already received or type its name, and add
property filters. The **Order shipped** and **Pix generated** recipes create
ready-made flows for `order_shipped` and `pix_generated`.

### Variables

The flow's messages (email, SMS and WhatsApp) read the event's properties as
variables:

| Variable | What it reads |
| - | - |
| `{{event.tracking.code}}` | A property, at any depth. |
| `{{event.items[0].name}}` | A list item, by position. |
| `{{event.carrier \| default: "Correios"}}` | The fallback text, used when the property was not sent or is empty. Single quotes work too. |

* A variable without a value or fallback makes the message be skipped, on any
  channel (email, SMS and WhatsApp), so the customer never receives the
  variable as written. The event records `missing_variable` on the flow
  ([flow warnings](#flow-warnings)). In official WhatsApp templates, use a
  dynamic variable to give a fallback text.
* A whole list or object is written as JSON. In email, the order items block
  shows `items[]` when the items follow the
  [catalog](https://docs.bevits.com/en/api-reference/recommended-events.md) format (`name`, `quantity`,
  `price_in_cents`, `image_url`, `url`).
* In the editor, the properties already received appear in the **Event** group
  of the variable picker.

### Conditions

A condition node compares an event property with `field: "event.<path>"`. The
property is compared as the type of the value given: number, boolean or text,
and a list with `includes`.

```json theme={null}
{
  "key": "express",
  "type": "condition",
  "field": "event.shipping.express",
  "operator": "equals",
  "value": true,
  "if_true": "notify"
}
```

Properties have no schema: a property of another type cannot be compared, so
the condition is false and the run records why. In the editor, the condition
node offers the **Event** group, with the properties already received and the
type of each one.

### Waiting for and ending on an event

A flow can also **listen** to events of the same customer while it runs. These
are two uses of the same mechanism:

* **Wait for event**: a block that pauses the execution until the event
  arrives, with a time limit of up to 90 days. It has two ways out: *arrived*
  (`if_arrived`) and *timed out* (`if_timed_out`).
* **End when it arrives**: on the trigger, events that end the execution as
  soon as they arrive (`trigger.exit_on`, up to 5). For example, a Pix payment
  reminder ends when `payment_confirmed` arrives.

```json theme={null}
{
  "name": "Pix with a reminder",
  "trigger": {
    "platform": "custom",
    "event": "pix_generated",
    "exit_on": [{ "event": "order_cancelled", "match_on": "order_number" }]
  },
  "start": "code",
  "nodes": [
    { "key": "code", "type": "send_whatsapp", "template_id": "wtp_…", "next": "paid" },
    {
      "key": "paid",
      "type": "wait_for_event",
      "event": "payment_confirmed",
      "match_on": "order_number",
      "timeout_amount": 15,
      "timeout_unit": "minutes",
      "if_arrived": "thanks",
      "if_timed_out": "reminder"
    },
    { "key": "thanks", "type": "send_email", "template_id": "etp_…" },
    { "key": "reminder", "type": "send_whatsapp", "template_id": "wtp_…" }
  ]
}
```

* **An event that arrives earlier counts too.** Everything the flow listens to
  is registered when the execution starts. If `payment_confirmed` arrives
  before the execution reaches the wait block (or even before the flow starts),
  the block goes on at once through *arrived*, and an exit rule ends the
  execution before its first send.
* **`match_on` ties the event to the right order.** Without it, any event with
  that name from the same customer counts. With `"match_on": "order_number"`,
  only an event whose `order_number` equals the one in the event that started
  the flow counts, so a customer with two open orders doesn't have both ended
  by one payment. `10293` and `"10293"` are the same value. It only works in
  flows started by a custom event; if the starting event lacks the property,
  nothing matches.
* **`filters`** work like the trigger's: only an event that passes all of them
  counts.
* **Ending means cancelling.** The execution is cancelled and no later send goes
  out: every send checks for cancellation first.
* Test events (`bvt_test_`) and `backfill` events never count: one doesn't
  really happen, the other is imported history.
* The wait block counts its time limit from when the execution reaches it.
* Later blocks read the received event as `{{events.<name>.<path>}}`, for
  example `{{events.payment_confirmed.payment_method}}`. If the time runs out,
  these variables have no value: give them a fallback
  (`{{events.payment_confirmed.payment_method | default: "Pix"}}`).
* Instagram flows don't wait for or end on events.

In the dashboard, the **Wait for event** block is in the editor's sidebar, and
exit rules are on the trigger block, under **End when it arrives**. The **Pix
generated** recipe comes with a reminder that stops when `payment_confirmed`
arrives for the same `order_number`.

## Validating without storing

`POST /v1/events/validate` takes the same body and returns what
`POST /v1/events` would return, without storing anything and without changing
customers. Use it during development to see which customer would match, which
flows would be queued, and which warnings would come up.

```bash theme={null}
curl https://api.bevits.com/v1/events/validate \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "customer": { "email": "novo@exemplo.com.br" }
  }'
```

* It requires the `read` scope. A key with only `events:write` cannot validate.
* When sending would create the customer, the response carries
  `"customer": { "would_create": true }`.
* The returned event `id` is a placeholder: there is no event to read later.
* The errors are the same as on send.

## Sending in bulk

`POST /v1/events/bulk` takes up to 100 events and 1 MB per call. Each item has
the same format as `POST /v1/events`.

```bash cURL theme={null}
curl https://api.bevits.com/v1/events/bulk \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stock-CAM-01-2026-11-18" \
  -d '{
    "events": [
      {
        "name": "back_in_stock",
        "customer": { "email": "ana@exemplo.com.br" },
        "properties": { "product": { "sku": "CAM-01", "name": "Camiseta" } },
        "external_id": "stock_CAM-01_u_8842"
      },
      {
        "name": "back_in_stock",
        "customer": { "email": "bruno@exemplo.com.br" },
        "properties": { "product": { "sku": "CAM-01", "name": "Camiseta" } },
        "external_id": "stock_CAM-01_u_9120"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const events = interested.map((customer) => ({
  name: "back_in_stock",
  customer: { email: customer.email },
  properties: { product: { sku: "CAM-01", name: "Camiseta" } },
  external_id: `stock_CAM-01_${customer.id}`,
}));

const response = await fetch("https://api.bevits.com/v1/events/bulk", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BEVITS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "stock-CAM-01-2026-11-18",
  },
  body: JSON.stringify({ events }),
});

const batch = await response.json();

if (!response.ok) {
  throw new Error(`${batch.error.code ?? batch.error.type}: ${batch.error.message}`);
}

// results has the same order as events.
batch.results.forEach((result, index) => {
  if (result.status === "error") {
    console.error(events[index].external_id, result.error.code, result.error.param);
  }
});
```

```python Python theme={null}
import os
import requests

events = [
    {
        "name": "back_in_stock",
        "customer": {"email": customer["email"]},
        "properties": {"product": {"sku": "CAM-01", "name": "Camiseta"}},
        "external_id": f"stock_CAM-01_{customer['id']}",
    }
    for customer in interested
]

response = requests.post(
    "https://api.bevits.com/v1/events/bulk",
    headers={
        "Authorization": f"Bearer {os.environ['BEVITS_API_KEY']}",
        "Idempotency-Key": "stock-CAM-01-2026-11-18",
    },
    json={"events": events},
    timeout=60,
)
batch = response.json()

if not response.ok:
    error = batch["error"]
    raise RuntimeError(f"{error.get('code', error['type'])}: {error['message']}")

# results has the same order as events.
for event, result in zip(events, batch["results"]):
    if result["status"] == "error":
        print(event["external_id"], result["error"].get("code"), result["error"].get("param"))
```

The response is `200` with one result per event:

```json theme={null}
{
  "object": "event_batch",
  "created": 1,
  "duplicate": 1,
  "failed": 1,
  "results": [
    { "status": "created", "event": { "object": "event", "id": "evt_…" } },
    { "status": "duplicate", "event": { "object": "event", "id": "evt_…", "duplicate": true } },
    {
      "status": "error",
      "error": {
        "type": "validation_error",
        "code": "invalid_tax_id",
        "message": "tax_id must be a valid CPF or CNPJ. For other documents, identify the customer by external_id.",
        "param": "events[2].customer.tax_id"
      }
    }
  ]
}
```

* **It is not atomic.** Every event stands on its own. An invalid event fails
  alone and the others go on.
* `results` has the same order and length as `events`. Each `event` comes
  complete, as in the `POST /v1/events` response.
* The `param` of each error starts with the position of the event:
  `events[2].name`.
* The `200` does not mean everything was accepted. Check `failed` and resend
  only the items with `status: "error"` after fixing them.
* The whole batch is only rejected (`422`) when `events` is empty, has more
  than 100 items, or exceeds 1 MB (`batch_too_large`).
* **Order:** events are stored in the order sent. The order in which the flows
  of different events run is not guaranteed.

## Reading an event

`GET /v1/events/{event_id}` returns the event, the customer it was linked to,
and what happened to each flow. It works right after the event is sent.

```bash theme={null}
curl https://api.bevits.com/v1/events/evt_01jd2v9k3m8q4r5s6t7u8v9w0x \
  -H "Authorization: Bearer $BEVITS_API_KEY"
```

The body is the same `event` object as on send. In it, each flow that was
`queued` becomes `started` or `skipped` with the reason.

In the dashboard, **Settings → Events** shows the events received live, with
the customer found and the result of each flow, and sends test events. It is
also where an event type gets a label and a nature, or is archived.

An event can be read by ID for the 13 months of history, with its
`properties` and the result of each flow. After that, the route responds `404`.

## Listing events

`GET /v1/events` lists the store's events, newest received first.
`GET /v1/customers/{customer_id}/events` is a customer's timeline, including the
events of customers that were merged into them.

```bash theme={null}
curl "https://api.bevits.com/v1/events?name=order_shipped&occurred_after=2026-11-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $BEVITS_API_KEY"
```

```json theme={null}
{
  "data": [{ "object": "event", "id": "evt_01jd2v9k3m8q4r5s6t7u8v9w0x", "name": "order_shipped", "...": "..." }],
  "has_more": true
}
```

| Parameter | Use |
| - | - |
| `name` | Only events with this name. |
| `customer_id` | Only this customer's events (`cus_…`), including those of customers merged into them. |
| `external_id` | The event sent with this `external_id`. |
| `occurred_after` | Happened at or after this moment (ISO 8601 with offset). |
| `occurred_before` | Happened before this moment. |
| `limit` | 1 to 100. Default: 25. |
| `starting_after` | The `id` of the last event of the previous page. |

* Each item is the same `event` object as `GET /v1/events/{event_id}`.
* An event shows up in listings as soon as it is accepted, without delay.
* Listings cover the 13 months of history. A test key lists test events; a
  live key lists live events.
* The history lives in an analytical store. If it is unavailable, listings
  respond `503`; `GET /v1/events/{event_id}` keeps answering for recent events.

## In the dashboard

* **Settings → Events → Rejected calls** shows, for 7 days, every call the API
  refused: the error, the field, the `request_id`, the key used and the body
  exactly as it was sent. In a batch, each refused event appears with its own
  body. After 7 days the record is deleted.
* The customer's **Events** tab in the CRM shows their timeline. Owners and
  admins can erase a customer's event history there (data protection): the
  properties leave Bevits right away and the history is removed within a day.
  The customer stays in the CRM.
* **Segments by event.** In the customer filter, the **Custom event** condition
  selects who did an event at least, at most or exactly N times, or never, in
  all history, in the last N days or between two dates, with up to 5 property
  filters (`items[].sku` includes `CAM-01`, `total` greater than 100). It
  combines with the other conditions through AND and OR. Test events never
  count; `backfill` events do. "Never" applies within the 13 months of history.

## Event types

`GET /v1/event-types` lists the event names the store has sent, with the
properties inferred from the events received.

```bash theme={null}
curl https://api.bevits.com/v1/event-types \
  -H "Authorization: Bearer $BEVITS_API_KEY"
```

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "event_type",
      "name": "order_shipped",
      "nature": "utility",
      "archived": false,
      "first_seen_at": "2026-11-18T17:03:01.000Z",
      "last_seen_at": "2026-11-18T19:40:12.000Z",
      "properties": [
        { "path": "order_number", "type": "string", "example": "10293" },
        { "path": "tracking", "type": "object" },
        { "path": "tracking.code", "type": "string", "example": "BR123" },
        { "path": "items", "type": "list" },
        { "path": "items[]", "type": "object" },
        { "path": "items[].quantity", "type": "number", "example": 2 }
      ]
    }
  ],
  "has_more": false
}
```

* `properties[].path` uses dots for objects and `[]` for list items. `type` is
  `string`, `number`, `boolean`, `date`, `list`, or `object`.
* The properties are a hint, not a constraint: an event with another shape is
  still accepted. They show up shortly after the event is received.
* `nature` is `utility` or `marketing`. Names from the
  [recommended events catalog](https://docs.bevits.com/en/api-reference/recommended-events.md) start with
  the nature from the catalog; other names start without this field.
* The list comes whole, without pagination. Archived types only appear with
  `?include_archived=true`.

## Send-only key

The `events:write` scope can stand alone on a key. It is the right key for a
backend that only feeds events: it sends, and it cannot read the customer base.

| Route | Accepted scope |
| - | - |
| `POST /v1/events` | `write` or `events:write` |
| `POST /v1/events/bulk` | `write` or `events:write` |
| `POST /v1/events/validate` | `read` |
| `GET /v1/events/{event_id}` | `read` |
| `GET /v1/events` | `read` |
| `GET /v1/customers/{customer_id}/events` | `read` |
| `GET /v1/event-types` | `read` |

With a send-only key:

* Any other route responds `403` with `missing_scope`.
* The send response carries `customer.id` only. `customer.matched_by` and
  `customer.created` are omitted.
* The identity warnings (`ambiguous_identifier`, `identifier_conflict`,
  `identifier_mismatch`) are omitted. Only `payload_mismatch` appears.

That way, a leaked key cannot be used to find out whether an email or phone
belongs to a customer of the store.

## Rate limits

The send routes have their own per-second limit, separate from the general
limit of 600 requests per minute.

| Route | Limit per API key |
| - | - |
| `POST /v1/events` | 100 requests per second |
| `POST /v1/events/validate` | 100 requests per second |
| `POST /v1/events/bulk` | 2000 events per second, counted per event |

Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and
`X-RateLimit-Reset`. On a `429`, wait the number of seconds in `Retry-After`.
The read routes (`GET /v1/events`, `GET /v1/events/{event_id}`,
`GET /v1/customers/{customer_id}/events` and `GET /v1/event-types`) use the
general limit.

## Test mode

With a test key (`bvt_test_…`), the event goes through all the validation and
resolution, but changes nothing in production:

* **It never creates or changes customers.** The response returns the customer
  that would match, or `"customer": { "would_create": true }` when sending
  would create one.
* **It never sends a message.** Flows show as `skipped` with
  `reason: "test_mode"`.
* **It is kept separate.** The event is stored with `livemode: false`. Events,
  event types, and the uniqueness of `external_id` are separate between test
  and production, and each key only reads the events of its own mode. Names
  seen only in test mode do not count toward the limit of 500.

## Consent when the customer is created

* An event **never changes** the opt-in or opt-out of a customer that already
  exists.
* A customer created by an event starts **without marketing opt-in**, unless
  the call carries `customer.consent`.
* `customer.consent` is only read when the event creates the customer.

```json theme={null}
{
  "name": "account_created",
  "customer": {
    "email": "ana@exemplo.com.br",
    "phone": "+5511988887777",
    "consent": { "email": true, "whatsapp": true }
  }
}
```

`consent.whatsapp` covers WhatsApp and SMS. `consent.email` covers email.

### Who receives the flow's messages

What a flow can send depends on the [nature of the
event](https://docs.bevits.com/en/api-reference/recommended-events.md#1-nature-of-the-event) that started
it and on the customer's consent on each channel:

| Customer | Marketing event | Utility event |
| - | - | - |
| Agreed to receive messages | receives | receives |
| Never agreed (including one created without `consent`) | does not receive | receives |
| Asked to leave | does not receive | does not receive |

* **Utility is about something the customer did**, such as an order's tracking
  or a Pix code. That is why it reaches customers who did not accept marketing.
* **On official WhatsApp, the template must be utility too.** A message only
  counts as utility when the event is a utility event and Meta approved the
  template in the utility category. A marketing template follows the marketing
  rule, even in a flow started by a utility event.
* **Events without a nature follow the marketing rule.** Each event type's
  nature can be changed in Settings → Events.
* **Email and WhatsApp are independent.** `consent: { "email": true,
  "whatsapp": false }` receives marketing emails and only utility WhatsApp and
  SMS. A customer who asked to leave every message receives no email.

A flow that could not reach the customer on any channel shows as `skipped`
with `no_consent`.

## Error reference

Every error follows the API envelope. For events, `error.code` names the
reason, `error.param` carries the full path of the field (`customer.email`,
`events[3].name`), and `error.suggestion`, when present, carries a value that
would be accepted. A rejected event stores nothing and touches no customer.

| HTTP | `error.code` | `error.param` | Meaning |
| - | - | - | - |
| `422` | `invalid_event_name` | `name` | The name does not follow the format. `suggestion` carries the corrected name, when there is one. |
| `422` | `missing_customer_identifier` | `customer` | `customer` has no identifier. |
| `422` | `unknown_field` | the field | The body has a field the API does not know. |
| `422` | `invalid_tax_id` | `customer.tax_id` | `tax_id` is not a valid CPF or CNPJ. For other documents, use `external_id`. |
| `422` | `invalid_phone` | `customer.phone` | The phone is not a valid number. |
| `422` | `attribute_type_mismatch` | `customer.attributes.<key>` | The value does not fit the type of the attribute that already exists. |
| `422` | `event_too_large` | | The event has more than 64 KB. |
| `422` | `too_many_properties` | `properties` | `properties` has more than 200 keys in total. |
| `422` | `properties_too_deep` | the path | `properties` has more than 5 levels. |
| `422` | `array_too_long` | the path | A list has more than 100 items. |
| `422` | `occurred_at_in_future` | `occurred_at` | `occurred_at` is more than 5 minutes in the future. |
| `422` | `occurred_at_too_old` | `occurred_at` | `occurred_at` is older than 13 months. |
| `422` | `too_many_event_names` | `name` | The store already has 500 active event names. |
| `422` | `event_type_archived` | `name` | The event type is archived. |
| `422` | `batch_too_large` | `events` | The batch has more than 1 MB. |
| `404` | `customer_not_found` | `customer.id` | No active customer has that `id`. |
| `403` | `missing_scope` | `scope` | The key does not have the scope the route requires. |

Other validation errors, such as a malformed email or an `occurred_at` without
an offset, respond `422 validation_error` with `param` and without `code`. The
remaining errors follow the [fundamentals](https://docs.bevits.com/en/api-reference/fundamentals.md#errors):

| HTTP | `error.type` | When |
| - | - | - |
| `400` | `invalid_request` | The body is not a JSON object, or the `event_id` in the route is invalid. |
| `404` | `not_found` | The event does not exist, belongs to the other mode (test or production), or is past its reading period. |
| `409` | `conflict` | The `Idempotency-Key` was already used with another body. |
| `429` | `rate_limited` | The per-second limit was exceeded. Wait for `Retry-After`. |
| `503` | `service_unavailable` | The event history is unavailable. Try again in a few minutes; reading a recent event by ID keeps working. |

## Next steps

> [card] [Recommended events](https://docs.bevits.com/en/api-reference/recommended-events.md)
>
> Suggested names and properties for the most common e-commerce events.

> [card] [Authentication](https://docs.bevits.com/en/api-reference/authentication.md)
>
> Create a send-only key with the `events:write` scope.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.