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.
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:
And this example response:
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
-1for 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
rejectCouponeffect with a
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:
acceptCouponindicates that a coupon with
setDiscountindicates that a discount with
My Cool Discountand
34.56in the application's currency should be applied to the order.
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.
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.
It indicates that the coupon code supplied was valid.
You should handle this effect by clearing any messages from
rejectCoupon effects and informing the user that the coupon is valid.
Other effects, such as setDiscount, provide more information about the actual rewards received.
It indicates that a coupon has been removed.
It indicates that a discounted session has been cancelled.
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.
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
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
Note about referrals
The effect of a successful referral can mean a free item for someone else, such as the referrer.
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.
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.
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 effect behaves similarly to couponCreated.
friendProfileIntegrationId parameter is empty, the referral code can be
redeemed by anyone having the code.
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.
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.
It indicates that a defined amount of loyalty points was successfully added to the customer's loyalty wallet.
The points only persist when the session is closed.
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.
It indicates that a session was cancelled in which loyalty points have been added.
Indicates that a session was cancelled in which loyalty points have been substraced.