# Events API {#events-api}


Use `POST /v1/my/events` when an action in your product should start or
personalize a Nitrosend flow. Your application remains the source of truth:
Nitrosend does not inspect your database or infer an event schema from
Supabase, Postgres, or another data store.


## Choose the event contract {#choose-the-event-contract}


For a custom event, you choose the name and the JSON fields in `data`.
Nitrosend accepts nested JSON objects and arrays; it does not require you to
map custom attributes to a fixed Klaviyo-style schema.

Keep each event contract stable once a flow uses it. For example, if a flow
expects `event.order.total`, continue sending that path with the same meaning
and value type.

Event names must start with a lowercase letter, contain only lowercase
letters, numbers, and underscores, and be at most 64 characters. The `data`
object can be at most 32 KB.

Some built-in events have required fields because their supplied flow recipes
use them. For example:

- `password_reset` requires `data.reset_url`.
- `order_shipped` requires `data.tracking_url`; `data.carrier` and
  `data.tracking_number` are optional.

Custom events remain open: their fields are defined by your integration.


## Send an event {#send-an-event}


Identify the contact by `contact_id` or `contact_email`, and always supply a
stable idempotency key so a retry cannot start the same flow twice.
`contact_id` must name an existing contact in the current brand. When both are
sent, `contact_email` is used.

When no contact in the brand holds `contact_email`, Nitrosend creates the
contact first: subscribed by default, or suppressed if the address is on your
account's suppression list. Its "New contact" flows start once, before the
event's own flows. An event never changes an existing contact's subscription,
so unsubscribes and suppressions stay in place. An invalid `contact_email`
returns `422`.



> [!WARNING]
> An event for a test or staff address creates a real contact, like any other
> address the brand has not seen.



```bash
curl -X POST https://api.nitrosend.com/v1/my/events \
  -H "Authorization: Bearer $NITROSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_8472_paid" \
  -d '{
    "event": "order_paid",
    "contact_email": "jane@example.com",
    "data": {
      "order": {
        "id": "8472",
        "total": 129.00,
        "currency": "AUD"
      },
      "plan": "pro"
    }
  }'
```

On the first request Nitrosend returns `201 Created`. Replaying the same event
name and idempotency key for the brand returns the existing event with `200 OK`.
Use an immutable source event ID for the key; do not reuse a key for changed
data.


## Use event data in a flow {#use-event-data-in-a-flow}


A flow with the `order_paid` trigger can read the payload under `event`:

```liquid
Order {{ event.order.id }} for {{ event.order.total }} {{ event.order.currency }}
```

When a field may be absent, give the email a safe default:

```liquid
Plan: {{ event.plan | default: "standard" }}
```

Create and test the event contract before activating the flow. This keeps the
producer and the email content aligned without requiring Nitrosend to own your
application schema.


## Orders and revenue {#orders-and-revenue}


Use `order_placed` or `purchase` to record an order as well as an event:

```json
{
  "event": "order_placed",
  "contact_email": "customer@example.com",
  "data": {
    "order_id": "order_8472",
    "order_number": "8472",
    "total": "47.94",
    "currency": "EUR",
    "items": [{
      "product_id": "prod_123",
      "product_name": "Kip met Peer",
      "quantity": 1,
      "item_price": "42.99",
      "product_url": "https://shop.example/products/123",
      "image_url": "https://shop.example/images/123.jpg"
    }]
  }
}
```

Amounts are major units, with at most two decimal places. Zero is valid;
missing is not zero. Currency is a three-letter code. `resource_uid` and
top-level `amount` can supply the order ID and total instead. Without both an
ID and a total, these remain ordinary events. `test: true` never records an
order or changes revenue.

The event and order commit together. Order history feeds the existing customer
commerce fields and revenue reports in the background. Up to 50 items are stored
on the Order, with truncation recorded; the event retains its original payload.
Only observed orders count, not an assumed history from before connection.

Use one financial feed per store. If your store already sends orders through
the Shopify or Stripe integration, do not send the same orders through this API
as well. IDs are not automatically matched across providers.

For a proven subscription renewal, send `order_type: "subscription_renewal"`.
It still contributes to customer order history and spend, but is not an
attributed conversion. First purchases and unclassified orders retain the
existing seven-day last-click attribution rule.


### Refunds and cancellations {#refunds-and-cancellations}


`order_canceled` needs `data.order_id`. `order_refunded` needs the same order ID,
a stable `data.refund_id` and a positive `data.refund_amount` in major units.
Each refund amount is incremental, not the replacement order total. A refund ID
applies once per order even if delivered under another event key. Supplied
currency must match; refunds cannot exceed the remaining order amount.

If the order has not arrived, Nitrosend returns retryable `409` with code
`order_not_recorded`. Record the purchase, then retry the correction with its
original idempotency key. No phantom order or consumed correction event remains.
Malformed amounts or conflicting currency return `422`.


### Products in emails {#products-in-emails}


In a flow email's existing product, product-grid or gallery controls, choose
**From the trigger event**. Campaigns have no trigger event and use fixed products.
Reusable templates may keep the binding for use in a flow. For example:

```json
{
  "type": "products",
  "binding": { "path": "event.items", "limit": 6 },
  "props": { "columns": "2", "button_text": "View product" }
}
```

A single card can use `event.product`, or `event.items` with an explicit
`index: 0`. Collection limits are 1–50. Grids and galleries are top-level;
a single card can sit inside columns. Empty collections show no placeholder
products. Include a product name and actual link; images and prices are optional.
Prices use the supplied unit amount and currency, never a current catalog price.

The original trigger event stays with the journey after a wait or resume. No
store crawl or dispatch-time product lookup runs. Paste a data object into
**Preview event products** to preview and test it. REST preview/test-send and
MCP test-send accept `event_data` for the same purpose; this does not record a
real event. Preview reports how many items are shown and whether they are limited.

Follow [Your first ecommerce flow](https://docs.nitrosend.com/guides/building-flows.md#your-first-ecommerce-flow)
to combine event products, a timed wait and a purchase exit before expanding to
more journeys.


## Supabase and other data stores {#supabase-and-other-data-stores}


Send the event from trusted server-side code after your application commits
the underlying change. With Supabase, this can be an Edge Function, database
webhook consumer, or application backend. Keep the Nitrosend API key on the
server; do not expose it in browser code.

The integration boundary is one explicit envelope:

```json
{
  "event": "your_event_name",
  "contact_id": 123,
  "data": { "your": "schema" }
}
```

Use `contact_email` instead of `contact_id` when your system stores email as
the shared identifier. An address the brand has not seen yet becomes a new
contact with only its email, so create or import the contact first when its
"New contact" flows need a name or other fields.

See the [API Reference](https://docs.nitrosend.com/integrations/api-reference.md) for list, lookup, and
filter operations on recorded events.
