API Integrations

Events API

Send product events to Nitrosend and use their data in automated flows

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_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

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.

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.