End-user guides:: Interactions - Event payload examples – Emarsys

In this article we have collected a few JSON payload examples that are used in Interactions programs.

Displaying the available attributes

To see all the available attributes of the selected event, choose from the following options:

If you selected the Event happened or Event did not happen Decision or Decision splitter node templates, click the attribute_name field and they will be listed in the drop-down.
If you selected the Trigger attribute template, then the attributes of the chosen Trigger event are listed in the drop-down when you click the attribute_name field.

You can enter attributes that you would like to use in the future manually.
The recommended Operators are automatically detected based on the attribute type.

In the following example, we selected the Trigger attribute template and all the available attributes for the Web Extend Viewed category list event are listed in the drop-down.

Web Extend events

Notes:

Currently, the product view, category view, cart update and purchase Web Extend events contain standard event payload. These events only contain product IDs without further product details, so please consider the following when defining conditions based on event attributes:
- Attribute filtering is available in the Event happened, Event did not happen and Trigger attributes templates of the Decision and Decision splitter nodes.
- Attributes in arrays (i.e. items enclosed in square brackets [ ]) are not listed in the drop-down after clicking the attribute_name field. To filter attributes in arrays, use the following attribute filters:
  - new_cart.items[0].item_id - It filters the first item based on its item_id. (If you would like to filter the second item, then change 0 to 1.)
  - purchase.items[0].price - It filters the first item based on its price. (If you would like to filter the second item, then change 0 to 1.)
You can filter for Mobile SDK events by using the EmarsysSDK value of the Web Extend attribute User agent in Interactions. In the following example, we have selected the Updated cart trigger event and added a Decision node to the program using the Trigger attributes template that contains the following attribute criteria: User agent contains EmarsysSDK. In this case, only those contacts will meet the specified criteria who triggered the Updated cart event and its payload contains the User agent EmarsysSDK.

The user_agent attribute contains browsing details that allow you to filter your contacts by the device or OS they are using. So, if you would like to recommend your visitors (who are browsing from desktop or mobile devices without using your app) to use your mobile app, then use the following attribute filters:

To filter contacts who browsed your product page by using a desktop computer with Windows OS, use the attribute filter user_agent contains Windows.
To filter contacts who browsed your product page by using an iPhone, use the attribute filter user_agent contains iPhone.

Purchase

You can use the Total cart value attribute within Purchase Web Extend events.

{
  "user_agent": "EmarsysSDK|osversion:9|platform:android",
  "remote_host": "192.168.17.43",
  "contact_id": 123456789,
  "purchase": {
    "order_id": "ABCD1E00F0002GH",
    "items": [
      { "item_id": "1234567", "price": 1.0, "quantity": 1.0 },
      { "item_id": "7654321", "price": 3.0, "quantity": 1.0 },
      { "item_id": "1122334", "price": 2.0, "quantity": 1.0 },
      { "item_id": "123456", "price": 5.0, "quantity": 1.0 },
      { "item_id": "4433221", "price": 4.0, "quantity": 1.0 },
      { "item_id": "1112223", "price": 1.0, "quantity": 1.0 }
    ]
  },
  "requesting_url": null,
  "previous_url": null,
  "language": null,
  "record_id": "20200707T144236Z_1298827028",
  "customer_id": 987654321,
  "event_time": "2020-07-07T14:42:36.000Z"
}

Click to copy

View

{
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; rv:11.0) like Gecko",
  "remote_host": "192.168.17.43",
  "contact_id": 123456789,
  "viewed_product": { "item_id": "16903452" },
  "requesting_url": "http://bestrun.com/women-sun-hat-compact-with-strap.html",
  "previous_url": "http://bestrun.com/women-sun-hat-compact-with-strap.html",
  "language": null,
  "record_id": "20200707T144058Z_604345501",
  "customer_id": 987654321,
  "event_time": "2020-07-07T14:40:58.000Z"
}

Click to copy

Category view

{
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1",
  "remote_host": "192.168.17.43",
  "contact_id": 123456789,
  "category": "Deals>Gift Cards",
  "requesting_url": "http://www.bestrun.com/",
  "previous_url": "http://bestrun.com/deals/gift-cards.html",
  "language": null,
  "record_id": "20200707T144145Z_123514338",
  "customer_id": 987654321,
  "event_time": "2020-07-07T14:41:45.000Z"
}

Click to copy

Cart update

Notes:

The items that were added to the cart during the cart update are listed under the line "items".
All the items that are currently in the customer’s cart are listed under the line "new_cart".
You can use the Total cart value attribute within Cart update Web Extend events.

{
  "contact_id": 12345678,
  "ms_since_last_cart_info": 123456789,
  "record_id": "20200707T132048Z_524507738",
  "items": [
    { "item_id": "1234567", "quantity": 1.0 },
    { "item_id": "7654321", "quantity": 1.0 },
    { "item_id": "123456", "quantity": 1.0 },
    { "item_id": "3214567", "quantity": 1.0 },
    { "item_id": "654123", "quantity": 1.0 }
  ],
  "new_cart": {
    "items": [
      { "item_id": "1234567", "price": 100.0, "quantity": 1.0 },
      { "item_id": "7654321", "price": 50.0, "quantity": 1.0 },
      { "item_id": "654123", "price": 10.0, "quantity": 1.0 },
      { "item_id": "3214567", "price": 40.0, "quantity": 1.0 },
      { "item_id": "112233", "price": 80.0, "quantity": 1.0 },
      { "item_id": "332211", "price": 120.0, "quantity": 1.0 }
    ]
  },
  "customer_id": 123456789,
  "language": null,
  "event_time": "2020-07-07T13:20:48.000Z"
}

Click to copy

Custom tags

You can send any custom defined attributes related to the tag to Emarsys, the following is just an example.
If you would like to personalize the content with attribute details, then enclose them as follows: {{ event.tag.attributes.yourCustomAttribute }}

{
    "tag": {
        "attributes": {
            "content_category": "shoes",
            "content_url": "url",
            "content_tag": "tag"
        }
    },
    "user_agent": "Mozilla/5.0",
    "requesting_url": "https://www.url.com/",
    "previous_url": "https://www.url.com/cart",
    "language": null,
    "event_time": "2021-06-06T01:01:01Z"
}

Click to copy

Mobile events

Please consider the following when defining conditions based on Mobile events:

Please make sure that you add the prefix event_attributes. to the attribute’s name, otherwise the specified attribute will be invalid. For example: event_attributes.yourCustomAttribute.
If you selected a Mobile event and would like to filter contacts based on the time when an event happened, use the event_timestamp attribute.
If you would like to personalize the content with event details in campaigns using Mobile events, then enclose them as follows: {{ event.event_attributes.yourCustomAttribute }}.
If you would like to add date type attributes to your custom Mobile events, please make sure that they comply with the ISO 8601 date format.

This is how the structure of a mobile event looks like:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://emarsys.com/schemas/mobile/default",
  "type": "object",
  "properties": {
    "event_name": { "type": "string" },
    "contact_id": { "type": "integer" },
    "customer_id": { "type": "integer" },
    "event_timestamp": { "type": "string" },
    "application_code": { "type": ["string", "null"] },
    "application_id": { "type": ["integer", "null"] },
    "hardware_id": { "type": ["string", "null"] },
    "event_attributes": { "type": ["object", "null"] }
  },
  "required": ["event_name", "customer_id", "contact_id"]
}

Click to copy

Sample Mobile event payload

{
    "event_name": "activity_finish",
    "contact_field_id": 123,
    "application_id": "EMS01-A1234", 
    "hardware_id": "1a23bc456de789f0",
    "event_timestamp": "2019-07-01T18:45:52.260Z", --> ISO 8601
    "event_attributes": {
      "duration": "4450",  
      "distance": "7089",
      "surface": "undefined",
      "calories": "678",
      "temperature": "22",
      "weather": "cloudy",
      "sport_type": "running",
      "feeling": "undefined",
            
  }
}

Click to copy

External events

Please consider the following when defining conditions based on External events:

If you would like to personalize the content with event details, then enclose them as follows: {{ event.yourCustomAttribute }}.
You can filter External events based on the time when they were received by Interactions with the ems_event_time attribute.
If you would like to add date type attributes to your custom External events, then please make sure that they comply with the ISO 8601 date format.

This is how an External event that was received through the API looks like:

Notes:

The external event’s schema needs to contain an identifier. For more information, see Create an External event.
The payload structure depends on whether the request is a single or batch call. For more information, see Payload Structure.

{
 "key_id": "id",
 "external_id": "123456789",
 "data": {
  "order_id": 9876543210,
  "order_state": "paid",
  "order_payment_method": "PayPal",
  "order_link": "https://yourwebsite.com/34469445770/orders/454dcdba23f61a43d2fcb0bd4dd53df7",
  "delivery_status": "postponed",
  "order_shipping_method": "standard_shipping",
  "order_discount_amount": 8,
  "order_grand_total": 67,
  "order_total_quantity": 6,
  "order_weight": 5.63,
  "order_address_country": "United Kingdom",
  "order_address_postcode": "NW1 6XE",
  "order_address_city": "London",
  "order_address": "221B Baker Street",
  "contact_id": 112233445,
  "event_time": "2020-05-14 13:10:38.000000 UTC"
 }	
}

Click to copy

Shopify events

You can use the following Shopify events in Interactions:

For more information on the event payload, see the Shopify Webhook documentation.

External event name in Emarsys	Topic / event type in Shopify
Customer Registration	customers/create
Order	orders/create
Order by New Customer	orders/create (`orders_count` is zero)
Order by Recurring Customer	orders/create (`orders_count` is not zero)
Order Paid	orders/paid
Order Cancelled	orders/cancelled
Order Fulfilled	orders/fulfilled
Order Partially Fulfilled	orders/partially_fulfilled
Order Updated	orders/updated
Refund	refunds/create
Fulfillments Created	fulfillments/create
Fulfillments Updated	fulfillments/update
Fulfillment Events Created	fulfillment_events/create
Fulfillment Events Deleted	fulfillment_events/delete

Adobe Commerce events

You can use the following Adobe Commerce events in Interactions:

For more information on the event attributes and their possible values, navigate to the Add-ons > Adobe Commerce page, click the View Event Data button and select an Adobe Commerce event.

Customer email and password changed
Customer email changed
Customer new account registered after guest order
Customer new account registered
Customer password reset from the admin panel
Customer forgot password
Customer resets password after login
Subscription confirmation required
Guest subscription confirmation required
Successful subscription
Successful guest subscription
Unsubscription
Guest unsubscription
Guest order refund
Invoice created on guest order
Invoice created on order
Guest order comment
Order comment
New order
Guest order shipment
Order shipment
Order refund
New guest order

Pub/Sub events

Currently, you can use the Emarsys Pub/Sub interface for the following purposes:

Triggering Interactions programs,
Making historical real-time decisions in Interactions,
Scheduling Wait for event nodes to wait for Pub/Sub events,
Creating segments based on custom Pub/Sub events.

Mandatory fields

The following fields are mandatory in each Pub/Sub payload:

You can use your own field names. Please contact your Implementation Consultant:

If you would like to use your own field names.
If you would like to change the field names after the implementation.

user_id: The customer’s external ID. Emarsys uses the value of this field to determine the contact ID. This field has to be present in your Emarsys contact database.
event_type: The name of the event that will be displayed on the UI (e.g. cart update, search, check-out page view, etc.). A single topic can contain multiple event types, so Emarsys will sort them out based on this field.

Currently, Emarsys can only process one event per message. So, please make sure that your event payload contains only one event_type field.
Pub/Sub events are invalid if their event_type field is longer than 1024 bytes.

event_id: A universally unique identifier (UUID) based on which Emarsys can deduplicate the events. It has to be unique within a single event type.

If you need help to generate UUIDs, visit the following page: https://www.uuidgenerator.net/version4.

event_time: The time when the event happened. The format of this field should comply with the ISO 8601 date format. Expired events are sorted out based on this field and it also has a crucial role in making historical decisions.

This is how a Pub/Sub event payload looks like:

{
  "user_id": "crake@example.com",
  "event_type": "delivery update",
  "event_id": "6208dcf7-c98f-4ade-88e8-1741b1fa193e",
  "event_time": "2020-09-22T07:05:13.164Z",
  "order_id": 1234567890,
  "order_state": "paid",
  "order_payment_method": "PayPal",
  "order_link": "https://yourwebsite.com/34469445770/orders/454dcdba23f61a43d2fcb0bd4dd53df7",
  "delivery_status": "postponed",
  "order_shipping_method": "standard_shipping",
  "order_discount_amount": 8,
  "order_grand_total": 67,
  "order_total_quantity": 6,
  "order_weight": 5.63,
  "order_address_country": "United Kingdom",
  "order_address_postcode": "NW1 6XE",
  "order_address_city": "London",
  "order_address": "221B Baker Street",
  "contact_id": 987654321,
  "event_time": "2020-05-14 13:10:38.000000 UTC"
}

Click to copy

Testing Interactions programs triggered by Pub/Sub events

To test programs triggered by Pub/Sub events, you need to use valid user IDs that are present in the Emarsys contact database. Otherwise, your contact will not enter the program.

Wishlist events

If you would like to use the Wishlist event, please contact your Client Success Manager.

{
  "key_id": 3,
  "events": [
    {
      "external_id": "test@example.com",
      "trigger_id": "ebf90e7e-0962-4942-96f9-f30b9456f871",
      "event_time": "2020-11-11T15:32:12Z",
      "wishlist_content": [
        {
          "item_id": "item_1",
          "quantity": 1
        },
        {
          "item_id": "item_2",
          "quantity": 5
        },
        {
          "item_id": "item_4",
          "quantity": 4
        }
      ],
      "event_attributes": {
        "store_name": "Boise",
        "shop_assistant_name": "Elise",
        "store_id": 264
      }
    }
  ]
}

Click to copy

Channel Engagement events

Here you can see the available Reply Categories and their payload IDs:

Out of Office (payload ID: 7) - Important: We do not recommend selecting the Reply Category Out of Office to avoid creating email loops. The contact’s out-of-office messages may trigger repeated auto-replies and vice versa.
Change-profile (payload ID: 8)
Unsubscribe (payload ID: 9) - Important: We do not recommend sending auto-replies for the Unsubscribe category to avoid sending unnecessary messages to contacts who have unsubscribed from your marketing campaigns.
Challenge Response (payload ID: 10)
Contact-us (payload ID: 11)
Unknown (payload ID: 12)

{
  "contact_id": "987654321",
  "campaign_id": "69974",
  "campaign_name": "Change profile request",
  "customer_id": "2101",
  "event_time": "2022-05-11T13:37:35+00:00",
  "trigger_id": "81df74965e7cc801034b80b4b37b4d42",
  "category": "9"
}

Click to copy

SAP Commerce Cloud events

If you have integrated your SAP Commerce Cloud store with Emarsys, then you can use the following events in Interactions:

Notes:

For more information on SAP Commerce Cloud events, see Events.
You can also check real event samples on the Add-ons > SAP Commerce Cloud Integration > Real-time events tab after clicking Event samples and selecting an event.

Product catalog updates events

If you would like to personalize the content with event details, then enclose them as follows: {{ event.yourCustomAttribute }}.

Price drop

{
    "contact_id": 123456789,
    "products": [
        {
            "item_id": "6",
            "event_time": {
                "value": "2019-08-15T07:44:16.000Z"
            },
            "old_price": 20,
            "new_price": 15,
            "last_seen": {
                "value": "2019-06-11T10:43:58.000Z"
            },
            "title": "Oryx and Crake (The MaddAddam Trilogy)",
            "image_url": "https://images-na.ssl-images-amazon.com/images/I/51mwR1ZxtWL._SX322_BO1,204,203,200_.jpg",
            "link": "https://www.amazon.com/Crake-MaddAddam-Trilogy-Margaret-Atwood/dp/0385721676",
            "msrp": 25
        }
    ],
    "customer_id": 1234,
    "criterion_id": "5d287aa67d13c400049655b9"
}

Click to copy

Low in stock

{
  "contact_id": 123456789,
  "products": [
    {
      "item_id": "123456",
      "event_time": {
        "value": "2023-02-03T07:31:08.000Z"
      },
      "last_seen": {
        "value": "2023-02-03T07:31:08.000Z"
      },
      "title": "test title1",
      "image_url": "https://testimg1",
      "link": "https://www.testurl1",
      "msrp": 29.99,
      "price": 29.99,
      "stock_amount": 3
    },
    {
      "item_id": "654321",
      "event_time": {
        "value": "2023-02-03T07:31:08.000Z"
      },
      "last_seen": {
        "value": "2023-02-03T07:31:08.000Z"
      },
      "title": "test title2",
      "image_url": "https://testimg2",
      "link": "https://www.testurl2",
      "msrp": 99.99,
      "price": 90.99,
      "stock_amount": 2
    }
  ]
}

Click to copy

Back in stock

{
    "contact_id": 123456789,
    "products": [
        {
            "item_id": "6",
            "event_time": {
                "value": "2019-08-15T07:44:16.000Z"
            },
            "new_price": 15,
            "last_seen": {
                "value": "2019-06-11T10:43:58.000Z"
            },
            "title": "Oryx and Crake (The MaddAddam Trilogy)",
            "image_url": "https://images-na.ssl-images-amazon.com/images/I/51mwR1ZxtWL._SX322_BO1,204,203,200_.jpg",
            "link": "https://www.amazon.com/Crake-MaddAddam-Trilogy-Margaret-Atwood/dp/0385721676",
            "msrp": 25
        }
    ],
    "customer_id": 1234,
    "criterion_id": "5d287aa67d13c400049655b9"
}

Click to copy

Need assistance with your Emarsys product? We'll get you the help you need!

Interactions

Displaying the available attributes

Web Extend events

Purchase

View

Category view

Cart update

Custom tags

Mobile events

External events

Shopify events

Adobe Commerce events

Pub/Sub events

Mandatory fields

Testing Interactions programs triggered by Pub/Sub events

Wishlist events

Channel Engagement events

SAP Commerce Cloud events

Product catalog updates events

Price drop

Low in stock

Back in stock

Need assistance with your Emarsys product?
We'll get you the help you need!