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: