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

By default, Iterable generates a unique id value for each custom event, and includes the generated id value in the API response body. You should store this in case you need to update the event later.

Here is an example API response body from POST /api/events/track when Iterable generates a unique id value for a custom event:

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

# Providing id values when tracking custom events

Optionally, you can provide a unique identifier for the event when sending a custom event to Iterable via the the POST /api/events/track or POST /api/events/trackBulk API endpoints.

When you provide an id value in these endpoints, Iterable uses it to update the event if it already exists. If it does not exist, Iterable creates a new event with the provided id value.

If you provide an id value, it must:

• Contain only alphanumeric characters and hyphens.
• Be no longer than 512 bytes in length.
• If the intention is to update the event, it must be an existing identifier.
• If the intention is to create a new event, it must be a truly unique identifier.

# 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}}