Intro
Endpoint: https://api.omnisend.com/api/events
Guide: How to send events using Events API
Send customer events to Omnisend to track behavior and trigger automations. Events can be recommended (predefined e-commerce actions) or custom (user-defined for flexible tracking).
Event Types
| Type | Description |
|---|---|
| recommended | Predefined events with specific names and properties (e.g., "placed order", "added product to cart"). Enable pre-built automations, reporting, and segment templates. |
| custom | User-defined events with arbitrary names and properties. Used for custom automation triggers, segmentation rules, and contact profile tracking. |
For a full list of recommended events and their schemas, see the Events Overview.
Version and Origin
Every event requires origin and recommended events require eventVersion. Incorrect values can cause issues with automations, segmentation, and reporting.
| Field | Recommended events | Custom events |
|---|---|---|
| eventVersion | Predefined per event — see each event's documentation | Not required, can be omitted |
| origin | api for custom stores, app name for 3rd-party apps | api for custom stores, app name for 3rd-party apps |
Note: If you are an e-commerce platform building an integration, contact Omnisend for origin guidance.
Event Deduplication
To avoid processing duplicate events, include both eventID and eventTime in the payload. Events with the same eventID and eventTime are processed only once.
Warning: Deduplication works only for historical events. It does not apply to real-time events used for automations.
Example: Send a custom event
curl --request POST \
--url https://api.omnisend.com/api/events \
--header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
--header 'Omnisend-Version: 2026-03-15' \
--header 'Content-Type: application/json' \
--data '{
"eventName": "my custom event",
"origin": "api",
"contact": {
"email": "[email protected]"
},
"properties": {
"customField": "value"
}
}'Example: Send a recommended event
curl --request POST \
--url https://api.omnisend.com/api/events \
--header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
--header 'Omnisend-Version: 2026-03-15' \
--header 'Content-Type: application/json' \
--data '{
"eventName": "added product to cart",
"origin": "api",
"eventVersion": "",
"eventID": "f3f61bc6-07b8-4645-92d8-189d882dbcb1",
"eventTime": "2024-07-01T12:00:00Z",
"contact": {
"email": "[email protected]"
},
"properties": {
"abandonedCheckoutURL": "https://example.com/checkout",
"cartID": "cart-123",
"currency": "USD",
"lineItems": [
{
"productID": "prod-1",
"productTitle": "Running Shoes",
"productPrice": 79.99,
"productQuantity": 1,
"productURL": "https://example.com/products/running-shoes",
"productImageURL": "https://example.com/images/running-shoes.jpg"
}
],
"value": 79.99
}
}'For the full list of properties for each recommended event, see the individual event pages linked from the Events Overview.