Custom Event Properties

Custom events are designed to help you track any active or passive event or action related to a user that Iterable doesn't already track as a system event.

This article reviews how you can view and manage the fields (or properties) of custom events so that you can use them in your marketing campaigns.

# In this article

# Viewing custom event fields

Users who have the Manage Settings project permission can access the Data Schema Management screen to view and manage custom events.

To view the data fields for a custom event, find the event in the Data Schema Management page and click on its name. Here, you can see each event field, its data type, and when it was created.

# Custom event id

When sending a custom event to Iterable via the POST /api/events/track or POST /api/events/trackBulk API endpoints, an optional string id parameter may be passed.

If no id is specified, then Iterable generates a value for the event's id and includes it in the API response body. To update an event later, make sure to provide an id value or save the one that Iterable generates.

If an event exists with that id, the event will be updated.

If you provide an id value, it must:

• Contain only alphanumeric characters and hyphens.
• Be no longer than 512 bytes in length.
• Be unique across all custom events in the project.

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 track request:

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

# Including custom fields for an event

Event properties are different from user profile fields because they are not stored on the user profile. Instead, they are tied to the event.

If an event was used to trigger a campaign in a journey, then you can insert event properties using Handlebars. This includes additional custom fields.

You can nest custom fields as an array of key:value pairs in the dataFields property when you use the following endpoints:

• POST /api/events/track
• POST /api/events/trackBulk

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 a shipping confirmation email template.

Suppose Iterable receives the following orderShipped event and uses it to trigger a shipping confirmation email in a journey:

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

# Using event properties to customize a template

You can dynamically insert event properties into a message with Handlebars. However, it's important to note that the event's fields are only available to the template when the campaign is triggered by the custom event.

For example, if an orderShipped event includes a trackingUrl property, you can make a journey that's triggered when the orderShipped event happens. Next, add a journey step that sends a shipping confirmation email containing the trackingUrl to your user after their items have shipped.

This syntax will insert the actual tracking URL into the email template:

{{trackingUrl}}