Iterable Commerce Event Properties

Iterable's commerce events are designed to help you track the items in a user's shopping cart and the items they purchase.

This article reviews the properties of commerce events that you can use in your marketing campaigns.

# In this article

# updateCart event

Update cart events track the items in a user's shopping cart, which can be essential information for abandoned cart campaigns. Shopping cart items are stored in the user's profile as shoppingCartItems, which is a JSON object array, and can be used to personalize messages.

# updateCart event properties

Update cart events contain the following properties that you can use in your marketing campaigns. Some of these fields are optional and may not be included in every update cart event, depending on your implementation.

# eventType

It's important to note that Iterable tracks update cart events as a type of custom event, which impacts the way you can use the event properties in Iterable.

The properties that distinguish this event from other custom events are "eventType": "customEvent" and "eventName": "updateCart".

To learn more about custom events, read Custom Event Properties.

# updatedShoppingCartItems

The updatedShoppingCartItems field in an update cart event contains an array of the items in the user's shopping cart.

Each item in the array has the following properties:

• id - A unique identifier for the item.
• sku - The item's stock keeping unit (SKU).
• name - The item's name.
• description - A description of the item.
• categories - An array of categories that the item belongs to.
• price - The price of the item.
• quantity - The quantity of the item purchased.
• imageUrl - A URL to an image of the item.
• url - A URL to the item's page on your website.
• any custom fields you have added to the item in dataFields.

# Example updateCart event

Here's an example of an update cart event tracked for a user.

Note that in addition to tracking this event, the user's shopping cart items are stored in the user's profile as shoppingCartItems.

{
    "createdAt": "2022-10-01T09:15:30.000Z",
    "dataFields": {
        "updatedShoppingCartItems": [
            {
                "categories": [
                    "Fitness",
                    "Exercise Equipment"
                ],
                "description": "Treadmill",
                "id": "123456789",
                "imageUrl": "https://example.com/treadmill.jpg",
                "name": "Treadmill",
                "price": 999.99,
                "quantity": 1,
                "sku": "TREADMILL001",
                "url": "https://example.com/treadmill"
            },
            {
                "categories": [
                    "Fitness",
                    "Dumbbells"
                ],
                "description": "Set of Dumbbells",
                "id": "987654321",
                "imageUrl": "https://example.com/dumbbells.jpg",
                "name": "Dumbbells",
                "price": 49.99,
                "quantity": 2,
                "sku": "DUMBBELLS001",
                "url": "https://example.com/dumbbells"
            }
        ]
    },
    "email": "user@example.com",
    "eventName": "updateCart",
    "eventType": "customEvent",
    "itblInternal": {
        "documentCreatedAt": "2022-10-01 09:15:30 +00:00",
        "documentUpdatedAt": "2022-10-01 09:15:30 +00:00"
    }
}

# purchase event

Purchase events track the items a user has purchased, as well as the campaign associated with a purchase. This data is helpful for attributing revenue to specific campaigns and identifying your most successful efforts. You can also use the purchase event to trigger post-purchase campaigns.

When a user makes a purchase, you can track the purchase event using the POST /api/commerce/trackPurchase endpoint. This event includes the items purchased, the total value of the sale, and other properties that you can use in your marketing campaigns.

When you track a purchase event, Iterable logs the event in the user's history and clears the user's shopping cart.

# purchase event system fields

Purchase events contain the following system-defined fields that you can use in your marketing campaigns. Some of these fields are optional and may not be included in every purchase event, depending on your implementation.

To view and manage your project's purchase event fields, including system and custom fields, go to Settings > Data Schema Management. To learn more about using this page, read Data Schema Management Overview.

# eventType

Iterable tracks purchase events as as a unique type of event. This event type is distinguished by the "eventType": "purchase" field.

# shoppingCartItems

The shoppingCartItems field in a purchase event contains an array of the items that the user purchased.

Each item in the array has the following properties:

• id - A unique identifier for the item.
• sku - The item's stock keeping unit (SKU).
• name - The item's name.
• description - A description of the item.
• categories - An array of categories that the item belongs to.
• price - The price of the item.
• quantity - The quantity of the item purchased.
• imageUrl - A URL to an image of the item.
• url - A URL to the item's page on your website.
• any custom fields you have added to the item in dataFields.

# total

The total value of the purchase.

# campaignId

The ID of the campaign that triggered the event.

# templateId

The ID of the template that triggered the event.

# Example purchase event

Here's an example of a purchase event tracked for a user, where
someCustomDataField is a custom property added to the event.

{
    "campaignId": 12345678,
    "createdAt": "2024-05-18T21:43:43.000Z",
    "email": "user@example.com",
    "eventType": "purchase",
    "eventUpdatedAt": "2024-05-18 21:43:43 +00:00",
    "itblInternal": {
        "documentCreatedAt": "2024-05-18 21:43:43 +00:00",
        "documentUpdatedAt": "2024-05-18 21:43:43 +00:00"
    },
    "shoppingCartItems": [
        {
            "categories": [
                "Fitness",
                "Exercise Equipment"
            ],
            "description": "Treadmill",
            "id": "123456789",
            "imageUrl": "https://example.com/treadmill.jpg",
            "name": "Treadmill",
            "price": 999.99,
            "quantity": 1,
            "sku": "TREADMILL001",
            "url": "https://example.com/treadmill"
        },
        {
            "categories": [
                "Fitness",
                "Dumbbells"
            ],
            "description": "Set of Dumbbells",
            "id": "987654321",
            "imageUrl": "https://example.com/dumbbells.jpg",
            "name": "Dumbbells",
            "price": 49.99,
            "quantity": 2,
            "sku": "DUMBBELLS001",
            "url": "https://example.com/dumbbells"
        }
    ],
    "templateId": 12345678,
    "total": 1099.97,
    "someCustomDataField": true
}

# Referencing shopping cart items

A common use case for commerce events is to personalize messages with shopping cart items.

When using Handlebars to personalize messages with shopping cart items, you can reference the items in the user's shopping cart in different ways.

When sending an API call to track a commerce event, shopping cart items belong nested in the items array of the API request body. However, Iterable saves the data stored in the items API request body in different object names which vary depending on where the data is stored.

To reference shopping cart items in your messages, use the following field names:

• User profile: profile.shoppingCartItems
• updateCart event: updatedShoppingCartItems
• purchase event: shoppingCartItems

To learn more about referencing arrays in Handlebars so you can display particular fields contained in the array for each item, read Working with Arrays.

# Referencing user profile field shoppingCartItems

To access a current list of the user's shopping cart items, such as with an abandoned cart campaign, use the user profile field, profile.shoppingCartItems. Adding profile as a prefix to the field name allows you to access the user's shopping cart items in the context of the user profile, which removes the need to reference the event that triggered the journey and provides the most current shopping cart information.

# updateCart event field updatedShoppingCartItems

When you set up a journey that triggers on a specific updateCart event, you can reference the items in the user's shopping cart using the updatedShoppingCartItems field. These references are only available in the context of the event that triggered the journey. If a user changes their shopping cart after the event, the journey doesn't reflect the updated cart.

# purchase event field shoppingCartItems

When you set up a journey that triggers on a specific purchase event, you can reference the items in the user's shopping cart using the shoppingCartItems field. These references are only available in the context of the event that triggered the journey.

Remember that the user's shopping cart is cleared after a purchase event, so the field profile.shoppingCartItems is empty after a purchase until there is a subsequent updateCart event that adds new items.