How to: send events rest api
Intro
Sending order or cart related events to Omnisend is crucial for effectively managing and nurturing customer relationships. By tracking such events, you can unlock a wealth of benefits for your merchant's business. These events enable advanced customer segmentation and the creation of targeted automations, such as order confirmation, cart abandonment, shipping confirmation, order follow-up and more. By leveraging this data, merchants can provide personalised, timely communication to their customers, improving their overall experience and increasing the likelihood of more purchases.
Authentication
/events
endpoint is protected and requires API key. During store connection, merchant will provide API key to you.
Events endpoint
To send events, Omnisend offers the /events
endpoint. This endpoint expects a specific request body format, as follows:
{
"eventName" : "{event name}",
"eventID": "{event id}",
"origin" : "api",
"eventVersion": "{event version}",
"contact":{
"id": "67447b7d5c1cd54488ec24d9",
"email": "[email protected]",
"phone": "+4423031237300",
"firstName": "Vanessa",
"lastName": "Kensington",
"birthdate": "1997-05-28",
"gender": "f",
"address": "9709 Highland Rd.",
"city": "New York",
"state": "NY",
"postalCode": "08723",
"country": "United States",
"customProperties": {
"favoriteColors": [
"red",
"blue"
],
"vipStatus": true,
"vipStatusDate": "2023-06-27T10:48:36Z",
"vipPoints": 100.59,
"friendlyTitle": "Miss Vanessa"
},
"tags": [
"vip",
"form:a12546asdwq"
],
"optIns": [
{
"channel": "email",
"createdAt": "2023-06-27T10:48:36Z",
"source": "form:omnisend-form:5d5cf027865hed74f4078q44:26"
}
],
"optOuts": [
{
"channel": "sms",
"createdAt": "2023-06-27T10:48:36Z",
"reason": "unsubscribed via email",
"source": "email link"
}
],
"consents": [
{
"channel": "email",
"createdAt": "2023-06-27T10:48:36Z",
"ip": "73.240.147.113",
"source": "form:omnisend-form:5d5cf027865hed74f4078q44:26",
"userAgent": "Mozilla/5.0"
}
]
},
"properties": {}
}
- eventName. Custom or recommended event name.
- eventID . This is an optional field. If you don't provide an event ID, Omnisend will generate one for you.
- origin. Use
api
- eventVersion. For cart events do not provide any version (leave it `
), for order events use
v2` - contact. Ensure you provide at least one of the following values: id, email and/or phone. All other contact information is OPTIONAL.
- properties.
It's important to note that you have the option to include custom properties in your events, which can then be utilised within the Omnisend platform for various marketing purposes and enhanced functionality.
Send cart events
We recommend two cart related events to be sent to Omnisend: added product to cart
and started checkout
. Both of them contributes to "Cart abandonment" automation.
Lets say a customer adds a product to their cart on your platform. In this situation, you should send an added product to cart
event to us.
Here's an example of how to do this:
curl --request POST \
--url https: //api.omnisend.com/v5/events \
--header 'X-API-KEY: MERCHANT_API_KEY'
--data '
{
"eventName": "added product to cart",
"eventID": "f1eeb5bd-736c-42c7-9cfe-6990f7f59b35",
"origin": "api",
"eventVersion": "",
"contact": {
"email": "[email protected]"
},
"properties": {
"abandonedCheckoutURL": "https://examople.com/cart/cartID/134035,",
"cartID": "134035",
"value": 19.99,
"currency": "EUR",
"addedItem": {
"productID": "373",
"productDescription": "Super duper product description",
"productImageURL": "https://example.com/inages/123.jpg",
"productPrice": 19.99,
"productTitle": "Super duper product",
"productURL": "https://example/com/abc"
},
"lineItems": [
{
"productID": "373",
"productDescription": "Super duper product description",
"productImageURL": "https://example.com/inages/123.jpg",
"productPrice": 19.99,
"productTitle": "Super duper product",
"productURL": "https://example/com/abc"
}
]
}
}
'
Send order events
Suppose a customer completes a purchase on your platform. In this case, you should send a placed order
event to Omnisend. Here's an example:
curl --request POST \
--url https: //api.omnisend.com/v5/events \
--header 'X-API-KEY: MERCHANT_API_KEY'
--data '
{
"eventName": "placed order",
"eventID": "f1eeb5bd-736c-42c7-9cfe-6990f7f59b35",
"origin": "api",
"eventVersion": "v2",
"contact": {
"email": "[email protected]"
},
"properties": {
"orderID": "P-6380-259017-3024",
"totalPrice": 84.99,
"createdAt": "2023-04-21T02:47:22Z",
"currency": "USD",
"paymentStatus": "pending",
"fulfillmentStatus": "unfulfilled",
"lineItems": [
{
"productID": "abc123",
"productImageURL": "https:/example.com/images/BF251-11KSR.jpg",
"productPrice": 84.99,
"productTitle": "Pink Rose Bouquet",
"productURL": "https://example.com/products/pink-rose-bouquet"
}
]
}
}
'
To learn more:
Updated 11 days ago