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
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_resetrequiresdata.reset_url.order_shippedrequiresdata.tracking_url;data.carrieranddata.tracking_numberare optional.
Custom events remain open: their fields are defined by your integration.
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.
An event for a test or staff address creates a real contact, like any other address the brand has not seen.
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
A flow with the order_paid trigger can read the payload under event:
Order {{ event.order.id }} for {{ event.order.total }} {{ event.order.currency }}When a field may be absent, give the email a safe default:
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
Use order_placed or purchase to record an order as well as an event:
{
"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
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
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:
{
"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 to combine event products, a timed wait and a purchase exit before expanding to more journeys.
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:
{
"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 for list, lookup, and filter operations on recorded events.
