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

# Recommended events

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

The API accepts **any event name** that follows the format (lowercase letters,
digits, and underscores). This catalog is a convention, not a rule: nothing
here is validated, and you can send events and properties that are not on the
list.

Following the catalog is worth it for two reasons:

* The same names and properties across all events keep flows and messages
  predictable: `{{event.order_number}}` works the same in `order_shipped` and
  in `order_delivered`.
* An event with a name from the catalog starts with the **nature** shown in the
  table (`utility` or `marketing`), returned by `GET /v1/event-types`.
* Some events have a ready-made flow in the Bevits recipes: **Order shipped**
  for `order_shipped` (reads `tracking_code`, `tracking_url` and `carrier`) and
  **Pix generated** for `pix_generated` (reads `pix_code` and `order_url`,
  reminds the customer 15 minutes later and stops when `payment_confirmed`
  arrives with the same `order_number`), and
  **Points expiring** for `points_expiring` (reads `points`).

See how to send them in [Custom events](https://docs.bevits.com/en/api-reference/custom-events.md).

## Common properties

Use these properties, with the same name, in every event where they make sense:

| Property | Content |
| - | - |
| `order_number` | Order number, as the customer sees it. |
| `order_url` | Link to the order. |
| `total_in_cents` | Total amount in cents. |
| `currency` | Currency, such as `BRL`. |
| `items[]` | Order items. Each item: `sku`, `name`, `quantity`, `price_in_cents`, `image_url`, `url`. |

In events about a product, `product` is an object with `sku`, `name`,
`price_in_cents`, `image_url`, `url`, and `category`.

```json theme={null}
{
  "name": "order_shipped",
  "customer": { "external_id": "u_8842", "email": "ana@exemplo.com.br" },
  "properties": {
    "order_number": "10293",
    "order_url": "https://loja.com/pedidos/10293",
    "total_in_cents": 15990,
    "currency": "BRL",
    "items": [
      {
        "sku": "CAM-01",
        "name": "Camiseta",
        "quantity": 2,
        "price_in_cents": 7995,
        "image_url": "https://cdn.loja.com/cam-01.png",
        "url": "https://loja.com/produtos/camiseta"
      }
    ],
    "tracking_code": "BR123",
    "tracking_url": "https://rastreio.exemplo.com.br/BR123",
    "carrier": "Correios",
    "estimated_delivery_date": "2026-11-22"
  },
  "external_id": "ship_10293"
}
```

## Catalog

| Group | Event | Recommended properties, besides the common ones | Nature |
| - | - | - | - |
| Order | `order_placed` | | utility |
| | `order_cancelled` | `reason` | utility |
| Payment | `pix_generated` | `pix_code`, `expires_at` | utility |
| | `pix_expired` | | utility |
| | `boleto_generated` | `boleto_url`, `barcode`, `due_date` | utility |
| | `payment_confirmed` | `payment_method` | utility |
| | `payment_failed` | `payment_method`, `reason` | utility |
| | `refund_issued` | `amount_in_cents`, `reason` | utility |
| Logistics | `order_invoiced` | `invoice_url`, `invoice_number` | utility |
| | `order_shipped` | `tracking_code`, `tracking_url`, `carrier`, `estimated_delivery_date` | utility |
| | `out_for_delivery` | `tracking_code`, `tracking_url` | utility |
| | `order_delivered` | `delivered_at` | utility |
| | `delivery_failed` | `reason`, `tracking_url` | utility |
| | `ready_for_pickup` | `pickup_location`, `pickup_deadline` | utility |
| Intent | `product_viewed` | `product` | marketing |
| | `search_performed` | `query`, `results_count` | marketing |
| | `product_added_to_cart` | `product`, `cart_url` | marketing |
| | `checkout_started` | `checkout_url` | marketing |
| | `wishlist_added` | `product` | marketing |
| Stock and price | `back_in_stock` | `product` | marketing |
| | `price_dropped` | `product`, `previous_price_in_cents` | marketing |
| After-sales | `review_requested` | `review_url` | utility |
| | `review_submitted` | `rating`, `comment`, `product` | |
| | `return_requested` | `reason`, `return_url` | utility |
| | `exchange_requested` | `reason` | utility |
| | `nps_answered` | `score`, `comment` | |
| | `support_ticket_resolved` | `ticket_id`, `survey_url` | utility |
| Loyalty | `points_earned` | `points`, `balance` | marketing |
| | `points_expiring` | `points`, `expires_at` | marketing |
| | `tier_changed` | `previous_tier`, `tier` | marketing |
| | `cashback_available` | `amount_in_cents`, `expires_at` | marketing |
| | `cashback_expiring` | `amount_in_cents`, `expires_at` | marketing |
| | `coupon_issued` | `code`, `discount`, `expires_at` | marketing |
| Subscription | `subscription_created` | `plan`, `next_charge_date` | utility |
| | `renewal_upcoming` | `plan`, `next_charge_date`, `amount_in_cents` | utility |
| | `subscription_renewed` | `plan`, `next_charge_date` | utility |
| | `subscription_payment_failed` | `plan`, `retry_date`, `update_payment_url` | utility |
| | `subscription_cancelled` | `plan`, `reason` | utility |
| Account and lead capture | `account_created` | `source` | marketing |
| | `lead_captured` | `source`, `form_name` | marketing |
| Physical store | `store_purchase` | `store_name` | utility |
| | `appointment_scheduled` | `scheduled_for`, `location` | utility |
| | `appointment_reminder` | `scheduled_for`, `location` | utility |

In the API, the nature shows as `utility` or `marketing`. Events without a
nature (`review_submitted`, `nps_answered`) usually generate no message: they
record the customer's answer.

Dates and times go as ISO 8601 text (`2026-11-22` or
`2026-11-22T14:00:00-03:00`). Monetary values go in cents.

## Three rules

### 1. Nature of the event

**Utility** is an event about something the customer already did: an order, a
payment, a delivery. **Marketing** is an event used to sell, such as
`back_in_stock` or `coupon_issued`, and the message it generates requires the
customer's consent.

The nature is a property of the event type. Names from the catalog start with
the nature from the table; a name outside the catalog starts without a nature
and follows the marketing rule. The nature can be changed in Settings → Events.
A utility event reaches customers who never accepted marketing, but not those
who asked to leave; on official WhatsApp, the template must be utility too.
Details in [Who receives the flow's messages](https://docs.bevits.com/en/api-reference/custom-events.md#who-receives-the-flows-messages).

### 2. Product events are sent per customer

`back_in_stock` and `price_dropped` happen to a product, but the API links each
event to a customer. Send one event per interested customer, using
[bulk sending](https://docs.bevits.com/en/api-reference/custom-events.md#sending-in-bulk).

### 3. Left out of the catalog on purpose

Password resets and verification codes are not in the catalog. They are
time-critical messages and do not belong in a marketing flow.

## If your store has no native integration

The native Bevits integrations already generate the events for an order being
created, paid, shipped, and cancelled, for an abandoned cart, and for a new
customer. If you send those facts through the API because you do not use a
native integration, use the names from the catalog: `order_placed`,
`payment_confirmed`, `order_shipped`, `order_cancelled`, `checkout_started`,
and `account_created`.


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