Skip to main content
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.
  • 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.
The key needs the write or events:write scope. See Send-only key.

Full request

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

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. What does not fit is rejected with 422 and an error.code. Nothing is truncated. 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. 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.
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

To find out what happened to a queued flow, read the 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.

Warnings

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:
  • 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, and condition nodes compare them with field: "event.<path>" (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:
  • 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). 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 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.
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.
  • 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.
  • 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.
The response is 200 with one result per event:
  • 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.
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.
  • 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.
  • 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 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. 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. 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.
  • 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.
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 that started it and on the customer’s consent on each channel:
  • 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. 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:

Next steps

Recommended events

Suggested names and properties for the most common e-commerce events.

Authentication

Create a send-only key with the events:write scope.