API Effects
The Integration API is your interface to the Talon.One rules engine.
Every customer session event in the Campaign Manager
triggers a request which is sent to the rule engine. The rule engine checks
if any rules apply to this request and returns an array of effects for each valid rule.
The rule engine applies these effects in the following ways:
- internally: for example, when updating a profile attribute.
- externally: the system making the API call applies the effect. For example
applying a discount to the shopping cart.
The following sections explain how to interpret the Integration API responses and which
effects the integration layer must handle.
Example Customer Session Update Response
The V2 Update a Customer Session
endpoint always returns an
array of effects, which might be empty. These are the results of rules that
matched the event.
For example, the following API request:
talon.updateCustomerSession('customer-1234', {"couponCodes": ["COOL123"]})
And this example response:
{
"effects": [
{
"campaignId": 54,
"rulesetId": 22,
"ruleIndex": 0,
"ruleName": "Cool-Summer Discount",
"effectType": "acceptCoupon",
"props": {
"value": "COOL123"
}
},
{
"campaignId": 54,
"rulesetId": 22,
"ruleIndex": 0,
"ruleName": "Cool-Summer!",
"effectType": "setDiscount",
"props": {
"name": "My Cool Discount",
"value": 34.56
}
}
],
"createdCoupons": [],
"createdReferrals": [],
}
Important: Ensure that your integration logic does not depend on the position of
*the effect array items.
Each entry in the effect array is a JSON object with the following properties:
campaignId: The ID of the campaign that caused this effect. Its value is -1 for
effects that are not associated with any campaign. For example, if a coupon code
is supplied and does not match any known campaign, the response is a
rejectCoupon effect with a campaignId of -1.rulesetId: The ID of the ruleset that caused this effect.ruleIndex: The position of the rule that caused this effect in the ruleset.ruleName: The name of the rule that caused this effect.effectType: The type of effect that was triggered.props: Additional properties of the effect, these are unique per effect type.
In this case, there are two effects:
acceptCoupon indicates that a coupon with value of COOL123 was accepted.setDiscount indicates that a discount with name of My Cool Discount and value
of 34.56 in the application's currency should be applied to the order.
Interpreting the different effect types
Let's look at the content of the effect itself. Only implement the
ones that you plan on using in campaign rules. The last 4 effect types in the
following list are only used for referral campaigns.
rejectCoupon
{
...
"effectType": "rejectCoupon",
"props": {
"value": "Cool-Summer!", // String - The coupon code that was rejected
"rejectionReason": "CouponNotFound" // String - The reason why this coupon was rejected
}
}
It indicates that the coupon code supplied was invalid.
You should handle this effect by informing their user the coupon code is invalid. See
all possible rejection
reasons.
acceptCoupon
{
...
"effectType": "acceptCoupon",
"props": {
"value": "Cool-Summer!" // String - The coupon code that was accepted
}
}
It indicates that the coupon code supplied was valid.
You should handle this effect by clearing any messages from
previous rejectCoupon effects and informing the user that the coupon is valid.
Other effects, such as setDiscount, provide more information about the
actual rewards received.
rollbackCoupon
{
...
"effectType": "rollbackCoupon",
"props": {
"value": "Cool-Summer!" // String - The coupon code whose usage has been rolled back
}
}
It indicates that a coupon has been removed.
rollbackDiscount
{
...
"effectType": "rollbackDiscount",
"props": {
"name": "MyDiscount", // String - The name of the "setDiscount" effect that was rolled back
"value": 10 // Number - The value of the discount that was rolled back
}
}
It indicates that a discounted session has been cancelled.
setDiscount
{
...
"effectType": "setDiscount",
"props": {
"name": "MyDiscount", // String - The name/description of this discount
"value": 10 // Number - The total monetary value of the discount
}
}
It indicates that a discount should be set on the total shopping cart value
of the current order with the given label and amount.
This discount should overwrite any existing discount with the same name. The most
recent integration state update always returns the latest values for all effects,
effectively overwriting any previous effects.
setDiscountPerItem
{
...
"effectType": "setDiscountPerItem",
"props": {
"name": "MyDiscountPerItem", // String - The name/description of this discount
"value": 10, // Number - The total monetary value of the discount
"position": 0 // Number - The index of the item in the cart items list on which this discount should be applied
}
}
It indicates that a discount per item should be set.
You should handle this effect by setting a discount on a specific line item in
the shopping cart.
Since one specific discount per item effect can apply to multiple shopping cart
items, an index is appended to the effect name. The position parameter indicates the
position of the item in the shopping cart, as it can also be seen in the
CustomerSession details.
addFreeItem
{
...
"effectType": "addFreeItem",
"props": {
"sku": "TEST-29372", // String - SKU of the item that needs to be added
"name": "Enjoy your free item" // String - The name/description of the effect
}
}
It indicates that a free item should be added to the shopping cart in the current
session. In this example, add the SKU to the shopping cart and set its price to 0.
Note about referrals: The effect of a successful referral can mean a free item for
someone else, such as the referrer.
showNotification
{
...
"effectType": "showNotification",
"props": {
"notificationType": "Error", // String - The type of notification that should be shown (e.g. error/warning/info)
"title": "An Error occurred", // String - Title of the notification
"body": "Please try again" // String - Body of the notification
}
}
You can use notifications to inform customers of certain events. There are 4 types of
notification messages:
It is up to the customer to use the rule builder to decide why and when they show
notifications.
A common use case is to display the notification on the top of the
cart. You can use the notification type to implement different styling of the
notification message.
updateAttribute
{
...
"effectType": "set",
"props": {
"path": "Profile.Attributes.Tier", // String - The exact path of the attribute that was updated
"value": "Gold" // String - The new value of this attribute. Value can be any of the following types (time, string, number, location, boolean) or a list of any of those types
}
}
Use the set effectType to update attribute values.
These are typically needed for internal use within the rule engine.
In certain cases, you can use these attributes to signal certain events to your system.
couponCreated
{
...
"effectType": "couponCreated",
"props": {
"value": "myPersonalCode", // String - The coupon code that was created
"profileId": "TestUser" // String - The integration identifier of the customer for whom this coupon was created
}
}
It indicates that a coupon was created.
For referrals and retention marketing, a common use case is to generate a coupon
that can only be redeemed by one specific customer.
Handle this effect by notifying the recipient about their new coupon code.
referralCreated
{
...
"effectType": "referralCreated",
"props": {
"value": "ReferralCode" // String - The referral code that was created
}
}
The referralCreated effect behaves similarly to couponCreated.
If the friendProfileIntegrationId parameter is empty, the referral code can be
redeemed by anyone having the code.
rejectReferral
{
...
"effectType": "rejectReferral",
"props": {
"value": "ReferralCode", // String - The referral code that was rejected
"rejectionReason": "ReferralNotFound" // String - The reason why this referral code was rejected
}
}
Similar to rejectCoupon, but for referral codes. It indicates that the
provided referral code is invalid.
You should handle this effect by informing the user that the referral code is invalid.
See all possible rejection
reasons.
acceptReferral
{
...
"effectType": "acceptReferral",
"props": {
"value": "Cool-Summer!" // String - The referral code that was accepted
}
}
Similar to acceptCoupon, but for referral codes.
It indicates that the referral code supplied is valid.
You should handle this effect by informing the user that the referral code is valid.
Other effects will provide more information about the actual reward.
addLoyaltyPoints
{
...
"effectType": "addLoyaltyPoints",
"props": {
"name":"10% of current total", // String - The name/description of this loyalty point addition
"programId":1, // Integer - The ID of the loyalty program where these points were added
"subLedgerId":"", // String - The ID of the subledger within the loyalty program where these points were added
"value":1.48, // Number - The amount of points that were added
"recipientIntegrationId":"example_prof_id", // String - The user for whom these points were added
"expiryCondition":"unlimited" // String - The amount of time (in days) these points are valid
}
}
It indicates that a defined amount of loyalty points was successfully added to the
customer's loyalty wallet.
Important: The points only persist when the session is closed.
deductLoyaltyPoints
{
...
"effectType": "deductLoyaltyPoints",
"props": {
"ruleTitle":"Cool-Summer!", // String - The title of the rule that contained triggered this points deduction
"programId":1, // Integer - The ID of the loyalty program where these points were added
"subLedgerId":"", // String - The ID of the subledger within the loyalty program where these points were added
"value":1 // Number - The amount of points that were deducted
}
}
It indicates that the loyalty points a customer wanted to spend got subtracted from
their loyalty wallet.
This effect is generated when there is a Loyalty points in program Loyalty can be
redeemed condition in an active campaign.
Important️: The points only persist when the session is closed.
rollbackAddedLoyaltyPoints
{
...
"effectType": "rollbackAddedLoyaltyPoints",
"props": {
"name": "always award 1 point with 1 minute pending window",
"programId": 302,
"recipientIntegrationId": "duff",
"subLedgerId": "",
"value": 1
},
"ruleIndex": 0,
"ruleName": "Berliner Discount 10",
"rulesetId": 283
}
}
It indicates that a session was cancelled in which loyalty points have been added.
rollbackDeductedLoyaltyPoints
{
...
"effectType": "rollbackDeductedLoyaltyPoints",
"props": {
"programId": 327,
"recipientIntegrationId": "duff",
"subLedgerId": "",
"value": 1
},
"ruleIndex": 0,
"ruleName": "Berliner Discount 10",
"rulesetId": 283
}
}
Indicates that a session was cancelled in which loyalty points have been substraced.
Last updated on 24th Feb 2021
