How to: send custom events to trigger custom automations

Introduction

There two types of events you can send to Omnisend:

recommended events are predefined with specific names and properties, designed to help you take advantage of Omnisend's pre-built automation presets, reporting capabilities, and segment templates. These events cover key e-commerce actions, such as "added product to cart," "started checkout," "placed order," and similar activities. To learn more about them click here
custom events are user-defined events that you create and implement according to your specific needs. Unlike recommended events, they do not have predefined names or properties and do not come with pre-built automation or segment templates. However, they offer flexibility for creating custom rules in segmentation, setting triggers and filters in automation, and are displayed in contact profiles for tailored tracking and analysis.

In this guide we will focus on custom events. Here are more examples what use cases you can cover:

Expiring Loyalty Points: Notify customers when their loyalty points are about to expire, encouraging redemption.
Reached a VIP Tier: Congratulate customers upon reaching a new VIP tier with exclusive benefits or offers.
Order Shipped: Send detailed shipping notifications, including tracking information and expected delivery dates.
Ask for a Review: Prompt customers to leave a review after receiving their purchase, boosting social proof.
Wishlist Update: Notify customers when items on their wishlist are back in stock or discounted, driving conversions.
Renewal Reminders: Alert customers when a subscription or service is about to renew or expire.
and many more

We will show you how to send custom events using either the JavaScript API for real-time events triggered directly from your website or the REST API for server-side events triggered by backend processes.

Sending Custom Events with the JavaScript API

To start sending custom events from your store, ensure the Omnisend snippet is added to your website. For more information, see the JavaScript Snippet Documentation.

Example code:

Call the following function in your website after customer made an action you want to track:

omnisend.push([
    "track",
    "added product to wishlist",
    {
        origin: 'api',
        properties: {
            product: {
                id: 'prod666',
                currency: 'USD',
                price: 66.66,
                oldPrice: 69.99,
                title: 'Container',
                description: 'Amazing container',
                imageUrl: 'http://www.example.com/images/products/prod-666.png',
                url: 'http://www.example.com/products/prod-666',
                status: 'inStock',
                categories: [
                    {
                        id: 'first',
                        title: 'containers'
                    }
                ]
            }
        }
    }
]);

Event name: "added product to wishlist" (Customize this to match your use case)
origin: 'api' is the source of the event.
properties: Contains all relevant event details (e.g., product info).

NOTE: Ensure the customer is identified before executing this code. It can be achieved by:

Customer clicked on a campaign email and landed on your website

Customer submitted Omnisend Form

Using the omnisend.identifyContact function

Sending Custom Events with the REST API

To send custom events from your backend, use the /events endpoint:

Example request:

curl --location 'https://api.omnisend.com/v5/events' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR API KEY' \
--data-raw '{
    "eventName": "earned loyalty points",
    "origin": "api",
    "contact": {
        "email": "[email protected]"
    },
    "properties": {
        "total_points_earned": 10,
        "tier": "vip"
    }
}'

eventName: Name of the event (e.g., "earned loyalty points")
origin: 'api' is the source of the event.
contact: Ensure at least one identifier (ID, email, or phone) is provided. All other contact information is optional. For detailed list of properties look here
properties: Custom event data (strings, numbers, timestamps, arrays, objects)

What's next?