API Effects

The Integration API is your interface to the Talon.One rules engine. Updates are received via the API, these are fed into the rule engine as events, and when a rule matches, it returns an array of effects. These effects may be applied internally by the rule engine, such as when updating a profile attribute, or they may need to be applied externally by the system making the API call, such as when adding a discount to a shopping cart. This reference explains how to interpret the Integration API responses and which effects need to be handled by a custom integration.

Example Integration API Response

Every operation in the Integration API returns an IntegrationState. This is an object containing the current customer session and profile, and the event that was recorded in response to this request. For example, given the following API request:

talon.updateCustomerSession('customer-1234', {})

You could receive the following response:

{
  "session": { ... },
  "profile": { ... },
  "event": {
    "type": "talon_session_updated",
    "attributes": {
      "isNew": false,
      "params": {
        "coupon": "FREESTUFF"
      }
    },
    "effects": [
      [ 59, 124, 0, ["acceptCoupon", "FREESTUFF"] ],
      [ 59, 124, 0, ["setDiscount", "My Cool Discount", 34.56] ]
    ]
  }
}

⚠️ Please make sure that your integration logic is not depending on the position of the effect array items.

We've omitted the session and profile details in order to focus on the event and it's effects. You can have a look of the structure of these objects here

The event contains a type, attributes, and an array of effects. These are the results of rules that matched the event. Each entry in the effect array is a 4-tuple of ID's and a Talang expression describing the effect:

• campaignId - The ID of the campaign that caused this effect. This will be -1 for effects that are not associated with any campaign. For example, if a coupon code is supplied that does not match any known campaign, the response will be 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.
• The effect itself.

The effect can be read as a function call. In this case, there are two effects acceptCoupon("FREESTUFF") and setDiscount("My Cool Discount", 34.56). The first simply indicates that the coupon was successfully validated by campaign 59, while the second indicates that the requester should apply a discount named "My Cool Discount" with an amount of 34.56 in the applications base currency.

Interpreting the different effect types

We will now zoom in on the content of the effect itself. It is only necessary to implement the ones that you actually plan on using in Campaign Rules. The last 3 effect types in the following list are only used for Referral Campaigns.

rejectCoupon

[
  "rejectCoupon", // effect type
  "FREESTUFF"     // coupon code
]

Used to indicate that the coupon code supplied was invalid. API clients should handle this effect by informing their user the coupon code is invalid.

acceptCoupon

[
  "acceptCoupon", // effect type
  "FREESTUFF"     // coupon code
]

Used to indicate that the coupon code supplied was valid. API clients should handle this by clearing any messages from previous rejectCoupon effects and informing the user that the coupon was validated. Other effects (such as setDiscount) will provide more information about the actual rewards received.

rollbackCoupon

[
  "rollbackCoupon", // effect type
  "FREESTUFF"     // coupon code
]

This effect can only be sent after cancelling a closed customer session. Used to indicate that a previously used coupon code is available, after it's usage has been rolled back. API clients should handle this effect by notifying the recipient that the coupon code is available once more.

setDiscount

[
  "setDiscount",      // effect type
  "My Cool Discount", // effect name (as configured in the Rule Builder)
  34.56               // amount in the currency of the application (as configured when creating the application in the Campaign Manager)
]

API clients should handle this effect by setting a discount on the total basket value of the current order with the given label and amount. This discount should overwrite any existing discount with the same name, since the most recent integration state update will always return the latest values for all affects, effectively overwriting any previously returned effects.

setDiscountPerItem

[
    "setDiscountPerItem",      // effect type
    "My Cool Item Discount#1", // effect name (as configured in the Rule Builder) + an index to indicate this is the nth
    45,                        // absolute number in the given currency
    0                          // the position (0-based) of the cart item this discount should apply to
]

API clients should handle this effect by setting a discount on a specific line item in the basket. Since 1 specific per item discount effect can apply to multiple basket items, we also append an index to the effect name. The position parameter indicates the position of the item in the basket, as it can also be seen in the CustomerSession details.

addFreeItem

[
  "addFreeItem",                // effect type
  "my_customer_integration_id", // the integration id of the Customer Profile this free item should be given to (if you don't use referrals, this will be the Customer Profile belonging to the current session)
  "SKU-456",                    // the SKU of the item to add (as configured in the Rule Builder)
  "A free item for you!"        // effect name (as configured in the Rule Builder)
]

Under most circumstances, API clients should handle this effect by updating the basket content in the current session. Add the SKU to the basket and set the price of it to 0. One notable exception is referrals: the effect of a succesful referral could mean a free item for someone else (i.e. the referrer).

showNotification

[
  "showNotification",                             // effect type
  "Info",                                         // notification type ('Info', 'Offer', 'Error', 'Misc')
  "Friday Funday!",                               // Notification title
  "Free delivery on orders over $50. Today only!" // Notification body
]

Notifications can be used to inform customers of certain events. There are 4 types of notification messages: 'Info', 'Offer', 'Error', 'Misc'. It is up to the customer to use the rule builder to decide why and when they show notifications. A common use case would be to display the notification on the top of the cart. The Type of notification can be used to implement different styling of the notification message (e.g. Info = Blue, Error=Red).

set

[
  "set",             // effect type
  "Profile",         // entity the attribute belongs to
  "Attributes",
  "HasOrderedToday",  // the attribute name
  true                // the new value of the attribute
]

Set is used to update attribute values. Often these are only needed for internal use within the Talon.One rule engine, but they will always be communicated as an FYI. For certain use cases, it can still be useful to use these attributes to signal certain events to your system.

couponCreated

[
  "couponCreated",       // effect type
  "COUPON4U",            // coupon code
  "customer_profile_id_123"  // Customer profile ID for the customer that can redeem this coupon
]

For referrals and retention marketing, it is a common use case to generate a coupon that can only be redeemed by one specific customer. API clients should handle this effect by notifying the recipient about their new coupon code.

referralCreated

[
  "referralCreated",       // effect type
  "REFERRALCODE",            // referral code
  "friendProfileIntegrationId"  // Customer profile ID for the customer that can redeem this referral code
]

The referralCreated effect behaves similarly to createCoupon effect. If the friendProfileIntegrationId paramater is empty, the referral code can be redeemed by anyone having the code.

rejectReferral

[
  "rejectReferral", // effect type
  "MYREFCODE"       // referral code
]

Similar to rejectCoupon, but for referral codes. Used to indicate that the referral code supplied was invalid. API clients should handle this effect by informing their user the referral code is invalid.

acceptReferral

[
  "acceptReferral", // effect type
  "MYREFCODE"       // referral code
]

Similar to acceptCoupon, but for referral codes. Used to indicate that the referral code supplied was valid. API clients should handle this by informing the user that the referral code was validated. Other effects will provide more information about the actual reward.

addLoyaltyPoints

[
  "addLoyaltyPoints",   // effect type
  1,                    // id of the loyalty program
  100,                  // amount of points
  "Enjoy your points",  // name of the effect
  "300h"                // points validity in hours
]

addLoyaltyPoints is used to indicate that a defined amount of loyalty points were successfully added to the customer's loyalty wallet.

⚠️ The points only persist when the session is closed.

deductLoyaltyPoints

[
  "deductLoyaltyPoints",  // effect type
  1,                      // id of the loyalty program
  12,                     // amount of points
  "Use points to pay"     // name of the rule the condition is in
]

deductLoyaltyPoints is used to indicate that the loyalty points a customer wanted to spend got subtracted from his loyalty wallet. This effect is generated when there is a "Loyalty points in program Loyalty can be redeemed" condition in an active campaign.

⚠️ The points only persist when the session is closed.