Events and Event Properties

An event is an action a user takes on your website or app. They are specific to your business.

Here are some sample events that an eCommerce website would be interested in tracking:

• Sign up
• Views an item
• Adds item to cart
• Purchase
• Order shipped
• User leaves review
• User refers a friend

Using the POST /api/events/track, POST /api/commerce/updateCart, or POST /api/commerce/trackPurchase API endpoints, you can send events to Iterable. These events can be used to trigger workflows, as segmentation queries, as filters in workflows and as custom conversion metrics. When naming events, make sure to make them as human-readable as possible. This makes it easier to understand which event corresponds with which action on your website or app.

# Event properties

When using the POST /api/events/track API, you can include dataFields to add event properties. For example, if you are sending over an orderShipped event, you may want to include shippingAddress and trackingURL as properties. This way, you can dynamically insert these properties into the shipping confirmation email template.

Event properties are different from user profile fields, because they are not stored on the user profile. Instead, they are tied to the event. You can insert event properties into an email if the same event was used to trigger the email in a workflow.

For example, suppose Iterable receives the following orderShipped event and uses it to trigger a shipping confirmation email in a workflow:

{
    "email": "ramona@example.com",
    "eventName": "orderShipped",
    "dataFields": {
        "shippingAddress": "929 Market Street, Suite 500, San Francisco, CA 94103",
        "trackingUrl": "iterable.com"
    }
}

To insert event properties into templates, wrap the field in double curly braces. For example:

{{shippingAddress}}

The event includes a shippingAddress event, which can be dynamically insert into a message with Handlebars (wrapped in double curly braces).

# Updating custom and purchase events

When sending a custom event to Iterable with the POST /api/events/track API endpoint or a purchase event with the POST /api/commerce/trackPurchase API endpoint, an optional string id parameter may be passed. If an event exists with that id, the event will be updated and any associated workflows will be triggered. If no id is specified, a new id will automatically be generated and returned.

Sample response where an id of "12345" is passed in the track request:

{
    "msg": "Event with id: 12345 tracked.",
    "code": "Success",
    "params": {
        "id": "12345"
    }
}

Sample response when no id is passed in the POST /api/events/track request:

{
    "msg": "Event with id: 0c1ecd665f0941db9088c9e390cb17e5 tracked.",
    "code": "Success",
    "params": {
        "id": "0c1ecd665f0941db9088c9e390cb17e5"
    }
}

# Viewing events

View a user's completed events by navigating to:

• The user's profile (Audience > Contact Lookup)
• The events log (Insights > Logs > Events)