Your account comes configured with multiple external events which are triggered by the Loyalty system. You can use them to either trigger an Automation program, an Interactions program or a Triggered email.
Loyalty external events can be used in Interaction Decision Splitter nodes. Their payload is also available, for example, to build conditional paths based on the users current tier and other properties.
You can find the external events under Management > External Events.
loyalty_tier_upgraded
loyalty_points_redeemed
loyalty_redeemed_voucher
loyalty_member_joined
loyalty_tier_downgraded
loyalty_tier_invitation_exit
loyalty_points_from_purchase_confirmed
loyalty_purchase_referee_confirmed
loyalty_member_deleted_by_contact
loyalty_member_deleted_by_customer
loyalty_cashback_redeemed
loyalty_tier_calculation
Tier upgrade
The loyalty_tier_upgraded
event is triggered at the moment a user has a tier upgrade. You can use it to create a triggered email that will be sent the moment the user has an upgrade. The event has the following parameters you can use inside the email, by using the following ESL code:
- Current Tier ID >
{{event.current_tier.id}}
; - Current Tier name >
{{event.current_tier.name}}
; - Current Tier icon >
{{event.current_tier.icon}}
; - Previous Tier ID >
{{event.previous_tier.id}}
; - Previous Tier name >
{{event.previous_tier.name}}
; - Previous Tier icon >
{{event.previous_tier.icon}}
;
Check the Upgraded to higher tier tactic, to see this event in action.
Tier downgrade
The loyalty_tier_downgraded
event is triggered at the moment a user has a tier downgrade (From regular tiers, not from Invitation only to regular tier). You can use it to create a triggered email that will be sent the moment the user downgraded to a lower tier. The event has the following parameters you can use inside the email, by using the following ESL code:
- Current Tier ID >
{{event.current_tier.id}}
; - Current Tier name >
{{event.current_tier.name}}
; - Current Tier icon >
{{event.current_tier.icon}}
; - Previous Tier ID >
{{event.previous_tier.id}}
; - Previous Tier name >
{{event.previous_tier.name}}
; - Previous Tier icon >
{{event.previous_tier.icon}}
;
Exit Invitation only tier
The loyalty_tier_invitation_exit
event is triggered at the moment a user moved from an Invitation only tier to a regular tier. You can use it to create a triggered email that will be sent the moment the user leaves the Invitation only tier, to say you are sorry they left the tier and would like to see them again. The event has following parameters you can use inside the email:
- Current Tier ID >
{{event.current_tier.id}}
; - Current Tier name >
{{event.current_tier.name}}
; - Current Tier icon >
{{event.current_tier.icon}}
; - Previous Tier ID >
{{event.previous_tier.id}}
; - Previous Tier name >
{{event.previous_tier.name}}
; - Previous Tier icon >
{{event.previous_tier.icon}}
;
Points redeemed
The loyalty_points_redeemed
event is triggered at the moment users redeem their points, for example, for a voucher. The event has only one parameter which you can use inside the email:
- Points >
{{event.points}}
- Tier name >
{{event.tier_name}}
Voucher redeemed
The loyalty_voucher_redeemed
event is triggered at the moment that the user redeems (uncovers) the voucher code in the Wallet or via API. You can use the event to send an email which will include the voucher code.
The event has the following parameters you can use inside an email, by using the following ESL codes:
- Voucher code >
{{event.code}}
; - Voucher name >
{{event.name}}
; - Tier name >
{{event.tier_name}}
Voucher used
The loyalty_voucher_used
event allows you to check if a loyalty voucher was used by the member during a purchase. It is triggered at the moment when the sales data is processed by Loyalty, if the loyalty voucher code was sent in the sales data file within the field s_coupon
. You can use it to create a Triggered Email or an Interactions program. The event has the following parameters in the payload which you can use within an email or as a filter in Interactions by using the following ESL snippets:
- Voucher code >
{{event.code}}
; - Voucher name >
{{event.name}}
; - OrderId >
{{event.orderId}}
;
Loyalty points confirmed from purchase
The loyalty_points_from_purchase_confirmed
event is triggered at the moment that the purchase points of Loyalty members are confirmed. You can use the event to create a triggered email that will update your members when their points are confirmed so they can check their balance, or you can send the details within the email. The event has following parameters you can use inside the email:
- # of points earned from this purchase >
{{event.points}}
; - Purchase OrderID >
{{event.order_id}}
; - Tier name >
{{event.tier_name}}
The points parameter will only show the regular purchase points the member will get. If there was a purchase action connected to the purchase, we will not return those additional points earned, but just the basic points.
Loyalty referral purchase confirmed
The loyalty_purchase_referee_confirmed
event is triggered the moment the referred friend made a purchase and the allocation period has passed. You can use the event to create a triggered email that will update your referrer that they have a reward waiting for them, because of the friend’s purchase. No parameters are available for this event.
Loyalty member joined
This event is triggered the moment a user is signing for your loyalty program, either via Loyalty API or the Wallet. You could use it to trigger a “Welcome Tactic”. This event has no additional data that can be used via ESL in an email.
For this external event to work, the user needs already to be in the Emarsys contact database and the field loyaltyid
needs to be filled in.
If you use the API to add a user to your loyalty program at the time when the user registers to your shop, do not use the member_joined
external event, as the contact is not yet created in Emarsys database. Therefore, the external event will not be able to start an automation program.
Loyalty member deleted
The external event loyalty_member_deleted_by_contact
is triggered when the contact cancels his membership via the Wallet, the external event loyalty_member_deleted_by_customer
is triggered when his membership is cancelled via the Member Profile. When the contact is deleted using the Loyalty API, it depends on the parameter sent in the API call which event is triggered: customer
or contact
. These events event have no payload.
Loyalty cashback redeemed
The external event loyalty_cashback_redeemed
is triggered when a member redeems a cashback voucher.
Loyalty tier calculation
The loyalty_tier_calculation
event is triggered at the moment a user has a tier calculation and stays in the same tier. The event has the following parameters you can use inside the email, by using the following ESL code:
- Current Tier ID >
{{event.current_tier.id}}
; - Current Tier name >
{{event.current_tier.name}}
; - Current Tier icon >
{{event.current_tier.icon}}
; - Previous Tier ID >
{{event.previous_tier.id}}
; - Previous Tier name >
{{event.previous_tier.name}}
; - Previous Tier icon >
{{event.previous_tier.icon}}
Use this external event to notify members, that they achieved the necessary amount of points to stay in their current tier.
To trigger a program in case when user is downgraded, please use the external event: loyalty_tier_downgraded
.
External events in the Automation Center
Important changes:
- Important changes in Automation Center programs starting with the External Event entry:
The optional field trigger_id
in External events is used for deduplication that you can define for each trigger. If an event is sent multiple times with the same trigger_id
, only the first one will be processed. If these IDs differ or are missing, the triggers are considered different and all of them will be processed.
From May 15, 2023 on, event deduplication with trigger_id
also applies to Automation Center programs starting with the External Event entry point that only contains Send email nodes.
Please make sure that you use this field appropriately until the mentioned date. Programs using the trigger_id
field inappropriately might result in unique events being dropped. For further assistance, please contact your Client Success Manager.
- The payload size limit of External events is changing:
We are introducing a limit of 500 KB for the payload size of External events effective July 1, 2023. Events exceeding this limit will not be accepted and you will receive an error response from the API. As a result, External events over the limit will not trigger any Triggered Email campaigns, Automation Center or Interactions programs.
To achieve optimal performance, we recommend using specific external events that supports your use case the best in programs starting with the External Event entry node instead of using a generic event in multiple programs.
Loyalty Tactics use the External event transactional entry point in the Automation Center.
Here contacts can enter a program if they are returned by an API call containing the same external event (you must first create the API call before you can use this node).
- If you include external data in the external event API call, this external data will remain available for that contact throughout their journey through the program and can be used to personalize further emails.
- Programs that start with this entry point follow the ignore opt-in rules for transactional programs. If you create a program that starts with one of these entry points, the first email in the program will be sent to all participating contacts regardless of their opt-in status (i.e. opt-in can be empty or
FALSE
). - External events may be used in as many active programs as you like.
Important:
- Email nodes in programs that start with a transactional entry node do not support Send Time Optimization.
- Emails that are used by programs starting with the External event entry point cannot be modified after launch.
- Attachments are currently not supported if the triggered email is the first email in an Automation Center program.
Notes:
- Transactional programs operate on individual user level and are triggered by user specific events.
- In that case you want to ignore opt-in, the Email node must be the first node after the External event entry node.
- When using the Transfer to program node in conjunction with the Entry from program entry point, please note that from programs that start with the External event entry point, only the Contact IDs are transferred to the linked program. The related payload is not passed. The external data will only be available in the source program.
- If you are using time zone support in the Automation Center, then time zone support will be enabled for absolute Wait nodes. For more information, see Transactional execution.
Copying the External event ID
You can copy the External event ID as follows:
After you selected an external event, its External event ID is displayed that you can copy by clicking the Copy ID icon. This comes in handy when you need to paste the External event ID into your external system.
Loyalty Trigger node in the Automation Center
You can create Automation Center programs that trigger Loyalty actions or assign rewards with this node.
Some actions require you to attach the specific action to your contacts. By doing so, the Loyalty system knows whom to reward when the action is completed.
Loyalty Trigger node in Interactions
Using the Loyalty Trigger node, you can build sophisticated automations with Emarsys in Interactions. You can quickly react to event related to your contacts engaging with your brand and involve them with Loyalty. For more information, see Channel nodes.