openapi: 3.2.0 info: title: Emarsys Core API - Events endpoint batch Wishlist API description: In this batch you may find endpoints related to events. version: v2 servers: - url: https://api.emarsys.net/api tags: - name: Wishlist paths: /v2/wishlist/update: post: summary: Trigger a Wishlist Update description: 'Activates a wishlist update event for the specified contacts. ### Prerequisites - If you synchronize your contact data using your own unique identifier in your system, a custom contact field `externalId` must exist as the external identifier. To create one, use the [Create a field](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4MTY) endpoint or go to **Admin** > **Field Editor** > **New** in the Emarsys application. For details on contact identifiers, see [Concepts](docs/before-you-start/concepts.md). >**Note:** Using external field identifiers is the recommended method for identifying contacts. However, you can use other Emasys system fields as well, such as email. For details, see [Contact system fields](docs/personalization/contact-system-fields.md). - The specified contact must exist in the Emarsys database to trigger an event. **Notes** - The maximum number of objects per request is 1000. - The maximum size of a single event is 20kB. - For Emarsys to follow-up changes, it is beneficial to have an initial load: we recommend sending through the current wishlist state for all your contacts with their corresponding event time. From that point on, Emarsys can calculate changes from the states (wishlist contents).' operationId: triggerWishlistUpdate parameters: - name: WSSE in: header required: true schema: type: string responses: '200': description: '' content: application/json: schema: type: object properties: replyCode: type: integer replyText: type: string data: type: object '400': description: '' content: application/json: schema: type: object properties: replyCode: type: integer replyText: type: string data: type: string '403': description: '' content: application/json: schema: type: object properties: replyCode: type: integer replyText: type: string description: This feature is not available in your account. data: type: string required: - replyCode - replyText - data 200a: description: '' content: application/json: schema: type: object properties: replyCode: type: integer replyText: type: string data: type: object properties: errors: type: object description: '`errors` is an `object` indicating failed processing of the events belonging to the listed contacts identified by the value of the specified `key_id`.' properties: jane.doe@example.com: type: object properties: '1008': type: string ? '' : type: string servers: - url: https://api.emarsys.net/api requestBody: content: application/json: schema: type: object properties: key_id: description: 'Identifies the contact by their `id`, `uid`, or the name/integer id of a custom field, such as `email`. When `id` or `uid` is used as identifier, provide value in this parameter and specify the the actual `id` or `uid` in the `external_id` parameter.' oneOf: - type: string - type: integer events: type: array description: The update event(s) in the batch. items: type: object properties: external_id: description: 'The external identifier of the field specified in the `key_id` parameter. Tip: Get the contact identifier at the [Get Contact Data](reference/openapi.json/paths/~1v2~1contact~1getdata/post) endpoint.' oneOf: - type: string - type: integer trigger_id: type: string description: The unique identifier of the wishlist update event. This field is used for deduplication. If an event is sent multiple times with the same `trigger_id`, only one gets processed. If these IDs differ or are missing, the triggers are considered different, and all of them are processed. event_time: type: string description: 'The time when the update event happened in UTC using the ISO 8601 format. In Interactions programs the expiration of the event is calculated based on this value.' wishlist_content: type: array description: '**Wishlist Content Overview** The wishlist content reflects the items currently present in the user''s wishlist after an update has occurred. Please note the following important details: **What to Expect When the Wishlist is Empty:** - **Empty Wishlist Possibility**: _The wishlist content can sometimes be empty_. This might happen when a user has cleared their wishlist or hasn''t added any items yet. - **Impact on Automated Programs**: If your automated programs are designed to send communications based on wishlist updates, an empty wishlist can cause the program to go to fail-safe. This means that if you haven''t filtered out empty wishlist events, your program may halt. An empty wishlist event will not be automatically filtered out or handled appropriately by the system unless you have configured it to do so. Manual intervention or specific program settings are required to handle such scenarios effectively. **Preventing Issues with Empty Wishlists:** - **Read More**: Please read the following resource: [Excluding contacts with empty wishlists from programs](https://help.emarsys.com/hc/en-us/articles/360020803417-Triggers-Wishlist-Event#excluding-contacts-with-empty-wishlists-from-programs). This guide provides important information on how to exclude contacts with empty wishlists—an essential step if you plan to maintain meaningful interactions and avoid fail-safe. - **Program Configuration**: Ensure that your marketing automation programs are configured to filter out or handle empty wishlist events properly. This can mean setting up conditional filters, alternative content paths, or exclusion rules to maintain the quality and relevance of your communications. By taking these steps, you can ensure that your marketing efforts remain effective and avoid the pitfalls associated with empty wishlist events.' items: type: object properties: item_id: type: string description: The unique identifier of the item, which is the same as your product ID in your Predict catalogue. Two items under `wishlist_content` cannot have the same `item_id`. The value entered here is case-sensitive. quantity: type: integer description: The quantity of the item. It must be a positive integer. If it is missing, "1" will be used. required: - item_id event_attributes: type: object description: Additional custom attributes to the event. Any field with any type of value can be provided. properties: myNumber: type: integer myString: type: string required: - external_id - event_time - wishlist_content required: - key_id - events x-examples: - 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: myNumber: 123 myString: yolo tags: - Wishlist components: securitySchemes: X-WSSE: type: apiKey name: X-WSSE in: header