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 one or more rules match, 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 Customer Session Update Response

The V2 Customer Session Update Endpoint will always return an array of effects. (If no effects were triggered, this array will be empty) For example, given the following API request:

talon.updateCustomerSession('customer-1234', {"couponCodes": ["COOL123"]})

You could receive the following 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": [],
}

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

The response will always contain an array of effects. These are the results of rules that matched the event. Each entry in the effect array is a json object with the following properties:

• 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.
• 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 "COOL123" was accepted.
• setDiscount to indicate that a discount with name "My Cool Discount" and value of "34.56" in the application's currency should be applied to the order.

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

{
  ...
  "effectType": "rejectCoupon",
  "props": {
    "value": "Cool-Summer!", // String - The coupon code that was rejected
    "rejectionReason": "CouponNotFound" // String - The reason why this coupon was rejected
  }
}

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. You can find all possible rejection reasons here.

acceptCoupon

{
  ...
  "effectType": "acceptCoupon",
  "props": {
    "value": "Cool-Summer!" // String - The coupon code that was accepted
  }
}

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

{
  ...
  "effectType": "rollbackCoupon",
  "props": {
    "value": "Cool-Summer!" // String - The coupon code whose usage has been rolled back
  }
}

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
  }
}

"rollbackDiscount" will be returned, whenever a discounted session gets cancelled.

setDiscount

{
  ...
  "effectType": "setDiscount",
  "props": {
    "name": "MyDiscount", // String - The name/description of this discount
    "value": 10 // Number - The total monetary value of the discount
  }
}

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

{
  ...
  "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
  }
}

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

{
  ...
  "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
  }
}

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

{
  ...
  "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
  }
}

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).

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
  }
}

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

{
  ...
  "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
  }
}

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

{
  ...
  "effectType": "referralCreated",
  "props": {
    "value": "ReferralCode" // String - The referral code that was created
  }
}

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

{
  ...
  "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. 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. You can find all possible rejection reasons here.

acceptReferral

{
  ...
  "effectType": "acceptReferral",
  "props": {
    "value": "Cool-Summer!" // String - The referral code that was accepted
  }
}

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

{
  ...
  "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
  }
}

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

{
  ...
  "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
  }
}

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.