24th Feb 2021

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:

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

Still need help? Get in touch!
Last updated on 24th Feb 2021

Was this article helpful?

Thank you! You have already voted

If you’d like a member of our support team to respond to you, please send a note to support@talon.one