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), andproperties(details). Optional:occurred_at,external_id, andbackfill. - 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.
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:
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.
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.nameupdates the customer’s name.customer.attributessets 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 asskippedwithno_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_mismatchwarning. It is not an upsert. - Without
external_id. Every call is a new event. The API never deduplicates on its own.
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.
id right away.
customer.matched_bysays which identifier found the customer. When the event created the customer,created: truecomes back andmatched_byis omitted.flowslists the active flows that listen to this name. An empty list means no flow is listening.warningsappears only when there is something to warn about. A warning never replaces an error.duplicate: trueappears 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 carryflows[].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 thecustom.<event_name> trigger.
Create the flow with POST /v1/flows, using platform: "custom" and the event
name in event:
trigger.filtersis optional and takes up to 10 filters. The flow starts only when all of them match the event’s properties.propertyis the path of the property, such astracking.carrieroritems[0].sku.- A property that is missing or has another type simply does not pass the
filter. The flow shows as
skippedwithfilter_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.
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_variableon 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 withfield: "event.<path>". The
property is compared as the type of the value given: number, boolean or text,
and a list with includes.
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 whenpayment_confirmedarrives.
- An event that arrives earlier counts too. Everything the flow listens to
is registered when the execution starts. If
payment_confirmedarrives 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_onties 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 whoseorder_numberequals 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.10293and"10293"are the same value. It only works in flows started by a custom event; if the starting event lacks the property, nothing matches.filterswork 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_) andbackfillevents 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.
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
readscope. A key with onlyevents:writecannot validate. - When sending would create the customer, the response carries
"customer": { "would_create": true }. - The returned event
idis 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.
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.
resultshas the same order and length asevents. Eacheventcomes complete, as in thePOST /v1/eventsresponse.- The
paramof each error starts with the position of the event:events[2].name. - The
200does not mean everything was accepted. Checkfailedand resend only the items withstatus: "error"after fixing them. - The whole batch is only rejected (
422) wheneventsis 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.
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
eventobject asGET /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[].skuincludesCAM-01,totalgreater than 100). It combines with the other conditions through AND and OR. Test events never count;backfillevents 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[].pathuses dots for objects and[]for list items.typeisstring,number,boolean,date,list, orobject.- 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.
natureisutilityormarketing. 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
Theevents: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
403withmissing_scope. - The send response carries
customer.idonly.customer.matched_byandcustomer.createdare omitted. - The identity warnings (
ambiguous_identifier,identifier_conflict,identifier_mismatch) are omitted. Onlypayload_mismatchappears.
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
skippedwithreason: "test_mode". - It is kept separate. The event is stored with
livemode: false. Events, event types, and the uniqueness ofexternal_idare 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.consentis 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.
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.