How to: sync historic orders

Introduction

This guide will walk you through the process of syncing historic orders to Omnisend. By syncing this data, you unlock powerful features, such as:

Segmentation: Segment contacts based on average order value, recent buyers, customer lifecycle stages, and more. For more information on customer lifecycle stages, see this guide
Reporting: Gain insights into your sales performance with comprehensive reporting tools.

WARNING: Before proceeding, make sure there are no automations setup in Omnisend that could send messages to customers based on the imported data. This could lead to sending duplicate messages to customers.

Order events

We recommend sending as many order events as you have in your system. It is important to cover a wide spectrum of events to ensure accurate reporting and segmentation. The most critical event is:

placed order

Additionally, other significant order-related events include:

order refunded
order canceled
paid for order
order fulfilled

By sending these events, you will enable more accurate reporting and comprehensive segmentation. Failure to provide certain events (e.g., order refunded, order cancelled) may lead to incorrect reporting data.

Syncing historic orders

To send historic order events to Omnisend, you can utilize the POST /batches endpoint. Here is an example:

curl --request POST \
     --url https://api.omnisend.com/v5/batches \
     --header 'Authorization: Bearer ACCESS_TOKEN' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "method": "POST",
    "endpoint": "events",
    "items": [
        {
            "contact": {
                "email": "[email protected]"
            },
            "eventName": "placed order",
            "eventTime": "2024-01-01T00:00:00Z",
            "eventVersion": "v2",
            "eventID": "f1eeb5bd-736c-42c7-9cfe-6990f7f59b35",
            "origin": "api",
            "properties": {
                "currency": "EUR",
                "fulfillmentStatus": "unfulfilled",
                "lineItems": [
                    {
                        "productCategories": [
                            {
                                "id": "123",
                                "title": "Shoes"
                            }
                        ],
                        "productDescription": "The best product with many various features",
                        "productID": "1",
                        "productImageURL": "https://example.com/product/232423-image.jpg",
                        "productPrice": 19.99,
                        "productQuantity": 2,
                        "productTitle": "The best product",
                        "productURL": "https://example.com/product/232423",
                        "productVariantID": "123",
                        "productVariantImageURL": "https://example.com/product/232423-variant-image.jpg",
                        "productVariantTitle": "Full product title - Green"
                    }
                ],
                "orderID": "4122111",
                "orderNumber": "4122111"
            }
        }
    ]
}
'

We recommend keeping the payload size limited to a maximum of 1MB to ensure optimal performance and efficient data transmission.

Important: make sure eventTime is set to the actual order creation date. Leaving it empty will default to the current date and time which might trigger unwanted automation workflows.

To learn more:

placed order event, check out the documentation.
POST /batches endpoint.