API effects

Effects are set in your rules. They represent what happened inside the Rule Engine so that you can apply the right action in your integration layer, if needed.

Example

If discount rule is validated, a setDiscount effect is returned to your integration layer, and you are responsible to apply this discount into your webshop.

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. Understanding the returned effects is a core concept of any integration.

The triggered effects can affect Talon.One, your external webapp, or both. For example:

Typically internal result: Updating a built-in attribute such as a customer profile's name. This only affects Talon.One but you can decide to use this effect in your ecommerce platform, if you need it.
Typically external result: Applying a discount to the shopping cart. Talon.One sends you the discount amount. You choose what to do with this information.

The following sections explain how to interpret the Integration API responses and which effects the integration layer must handle.

Locating the returned effects

The Update 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, consider the following rule:

Rule name: Check XMAS Coupon
Condition: Coupon code is valid
Failure effect: Create notification
Rule effect: Set a discount ([Session.Total] * 10%). Name: 10% off with XMAS coupon.

Now let's imagine a request where we communicate that a given customer session now has a valid coupon code added to it:

Update customer session body
{
    "customerSession": {
        "profileId": "{{Integration_id}}",
        "couponCodes": ["XMAS-2021"]
    }
}

And this example response returning two effects:

'effects' object in the response of rule effects
{
  "effects": [
      {
          "campaignId": 3882,
          "rulesetId": 14828,
          "ruleIndex": 0,
          "ruleName": "Check XMAS coupon",
          "effectType": "acceptCoupon", // The coupon code is valid
          "triggeredByCoupon": 4607465,
          "props": {
              "value": "XMAS-2021"
          }
      },
      {
          "campaignId": 3882,
          "rulesetId": 14828,
          "ruleIndex": 0,
          "ruleName": "Check XMAS coupon",
          "effectType": "setDiscount", // A discount was triggered by the rule
          "triggeredByCoupon": 4607465,
          "props": {
              "name": "10% off with XMAS coupon",
              "value": 20.0 // The value of the discount. You decide how to process it.
          }
      }
  ],
  "ruleFailureReasons": []
}

If the customer session did not have a valid coupon code added to it, consider the following example response returning the failure effect:

'effects' object in the response of a failure effect
{
  "effects": [
      {
          "campaignId": 3882,
          "rulesetId": 14828,
          "ruleIndex": 0,
          "ruleName": "Check XMAS coupon",
          "effectType": "showNotification", // The failure effect is applied for the invalid coupon
          "conditionIndex": 0,
          "props": {
              "notificationType": "Error",
              "title": "Failure notification",
              "body": "Coupon code is invalid. Enter a valid coupon code."
          }
      },
  ],
  "ruleFailureReasons": []
}

important

Ensure that your integration logic does not depend on the position of the effects array items.

Each entry in the effect array is an 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 the triggered effect.
conditionIndex: The position of the failed condition that triggered the effect among the other conditions in the rule. Only applicable for failure effects.
props: Additional properties of the effect. These are unique per effect type.

In our examples, there are three effects:

acceptCoupon indicates that a coupon with a value of XMAS-2021 was accepted.
setDiscount indicates that a discount with a name of 10% off with XMAS coupon and a value of 20.0 in the Application's currency should be applied to the order.
showNotification indicates that a notification was displayed because of an invalid coupon code.

Interpreting the different effect types

Each effect has a specific structure. Be ready to parse the ones you expect.

Achievements

The following API effects are returned when you use an achievement effect.

increaseAchievementProgress
rollbackIncreasedAchievementProgress

increaseAchievementProgress

It indicates that the customer's progress in the achievement was updated in the current session. It is triggered when a rule containing the Update customer progress effect is validated.

{
  "effectType": "increaseAchievementProgress",
  "props": {
    "achievementId": 10,
    "achievementName": "FreeCoffee10Orders",
    "progressTrackerId": 20,
    "delta": 1,
    "value": 5,
    "target": 10,
    "isJustCompleted": false
  }
}

Property	Type	Description
`achievementId`	integer	The internal ID of the achievement.
`achievementName`	string	The name of the achievement.
`progressTrackerId`	integer	The internal ID of the achievement progress tracker.
`delta`	number	The value by which the customer's current progress in the achievement has increased.
`value`	number	The current progress of the customer in the achievement.
`target`	number	The target value to complete the achievement.
`isJustCompleted`	boolean	Indicates if the customer has completed the achievement in the current session.

rollbackIncreasedAchievementProgress

It indicates that the customer's progress in an achievement was rolled back.

This gets triggered when you cancel or reopen a customer session where the Update customer progress effect was validated and the increaseAchievementProgress API effect was triggered. This effect cannot be triggered if the customer has completed the achievement.

{
  "effectType": "rollbackIncreasedAchievementProgress",
  "props": {
    "achievementId": 10,
    "achievementName": "FreeCoffee10Orders",
    "progressTrackerId": 20,
    "decreaseProgressBy": 1,
    "currentProgress": 5,
    "target": 10
  }
}

Property	Type	Description
`achievementId`	integer	The internal ID of the achievement.
`achievementName`	string	The name of the achievement.
`progressTrackerId`	integer	The internal ID of the achievement progress tracker.
`decreaseProgressBy`	number	The value by which the customer's current progress in the achievement has decreased.
`currentProgress`	number	The current progress of the customer in the achievement.
`target`	number	The target value to complete the achievement.

rejectCoupon

It indicates that the coupon code supplied couldn't be used.

You should handle this effect by informing their user the coupon code is invalid.

{
  ...
  "effectType": "rejectCoupon",
  "props": {
    "value": "SUMMER-2021-25",
    "rejectionReason": "CouponNotFound"
  }
}

Property Type Description

value String The coupon code that was rejected.

Property	Type	Description
`value`	String	The coupon code that was rejected.
`rejectionReason`	String	The reason why the code was rejected. `CouponExpired`: The coupon is expired. `CouponLimitReached`: The coupon redemption limit or a campaign budget was reached. `CouponNotFound`: The coupon code is incorrect. `CouponPartOfNotRunningCampaign`: The campaign the coupon belongs to is currently not active. The campaignId field contains the ID of that campaign. `CouponRecipientDoesNotMatch`: The given coupon value does not match the recipient or the coupon is linked to a `recipientIntegrationID` but there is no profile in the session. `CouponRejectedByCondition`: Other conditions failed in the rule or all conditions passed but the `Coupon code is valid` condition is not present. `CouponStartDateInFuture`: The coupon isn't active yet. `EffectCouldNotBeApplied`: One of the effects in the campaign wasn't applied because a limit for that effect was reached (most common use case will be `setDiscount` cannot be applied because a discount limit is reached). `ProfileLimitReached`: The profile-specific coupon redemption limit has been reached. `CouponPartOfNotTriggeredCampaign`: The campaign the coupon belongs to was not triggered during evaluation (an exclusive or stackable campaign). The `campaignId` field contains the ID of that campaign. `CouponReservationRequired`: The coupon's `isReservationMandatory` property is `true`, but the profile does not have a reservation. `ProfileRequired`: The coupon's `isReservationMandatory` property is `true` or a campaign profile budget was set, but no profile exists in the session.
`campaignExclusionReason`	String	The reason why the campaign the coupon belongs to was excluded during campaign evaluation, when `rejectionReason` was `CouponPartOfNotTriggeredCampaign`. Its possible values are: `CampaignGaveLowerDiscount`: The required campaign and coupon conditions were met, but another campaign in a Highest discount value group offered a higher discount value. `CampaignIsNotFirst`: The campaign was not evaluated because another campaign in a First campaign group was picked and evaluated first. `CampaignNotInEvaluationSet`: The campaign did not meet other evaluation requirements.

rejectionReason

String

The reason why the code was rejected.

CouponExpired: The coupon is expired.
CouponLimitReached: The coupon redemption limit or a campaign budget was reached.
CouponNotFound: The coupon code is incorrect.
CouponPartOfNotRunningCampaign: The campaign the coupon belongs to is currently not active. The campaignId field contains the ID of that campaign.
CouponRecipientDoesNotMatch: The given coupon value does not match the recipient or the coupon is linked to a recipientIntegrationID but there is no profile in the session.
CouponRejectedByCondition: Other conditions failed in the rule or all conditions passed but the Coupon code is valid condition is not present.
CouponStartDateInFuture: The coupon isn't active yet.
EffectCouldNotBeApplied: One of the effects in the campaign wasn't applied because a limit for that effect was reached (most common use case will be setDiscount cannot be applied because a discount limit is reached).
ProfileLimitReached: The profile-specific coupon redemption limit has been reached.
CouponPartOfNotTriggeredCampaign: The campaign the coupon belongs to was not triggered during evaluation (an exclusive or stackable campaign). The campaignId field contains the ID of that campaign.
CouponReservationRequired: The coupon's isReservationMandatory property is true, but the profile does not have a reservation.
ProfileRequired: The coupon's isReservationMandatory property is true or a campaign profile budget was set, but no profile exists in the session.

campaignExclusionReason

String

The reason why the campaign the coupon belongs to was excluded during campaign evaluation, when rejectionReason was CouponPartOfNotTriggeredCampaign.
Its possible values are:

CampaignGaveLowerDiscount: The required campaign and coupon conditions were met, but another campaign in a Highest discount value group offered a higher discount value.
CampaignIsNotFirst: The campaign was not evaluated because another campaign in a First campaign group was picked and evaluated first.
CampaignNotInEvaluationSet: The campaign did not meet other evaluation requirements.

acceptCoupon

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.

The code is automatically redeemed when you close the session.

Other effects, such as setDiscount, provide more information about the actual rewards received.

{
  ...
  "effectType": "acceptCoupon",
  "props": {
    "value": "SUMMER-2021-25"
  }
}

Property	Type	Description
`value`	String	The coupon code that was accepted.

couponCreated

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.

{
  ...
  "effectType": "couponCreated",
  "props": {
    "value": "SUMMER-2021-25",
    "profileId": "TestUser"
  }
}

Property	Type	Description
`value`	String	The coupon code that was created.
`profileId`	String	The integration identifier of the customer for whom this coupon was created.

rollbackCoupon

It indicates that a coupon code redemption has been rolled back. This coupon becomes redeemable again.

This effect happens when you cancel a session where a coupon was accepted. See an example of use in the cancelling a session tutorial.

{
  ...
  "effectType": "rollbackCoupon",
  "props": {
    "value": "SUMMER-2021-25"
  }
}

Property	Type	Description
`value`	String	The coupon code whose redemption has been rolled back.

reserveCoupon

It indicates that the given coupon code was reserved for the given customer.

Talon.One provides soft and hard reservations. For more information, see Reserving a coupon code.

{
  ...
  "effectType": "reserveCoupon",
  "props": {
    "couponValue": "SUMMER-2021-25",
    "profileIntegrationId": "URNGV8294NV",
    "isNewReservation": true
  }
}

Property	Type	Description
`couponValue`	String	The coupon code that was created.
`profileIntegrationId`	String	The integration identifier of the customer for whom this coupon was reserved.
`isNewReservation`	Boolean	Indicates whether this is a new coupon reservation or not.

Discounts

The effects happen when you use a Discount effect.

setDiscount
setDiscountPerItem
addFreeItem
setDiscountPerAdditionalCost
setDiscountPerAdditionalCostPerItem
rollbackDiscount

setDiscount

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.

Enabling partial discounts allows a rule that would fail because of insufficient budget to pass. The rule still fails when the budget reaches 0. Use the desiredValue property to identify the original value of the discount.

{
  ...
  "effectType": "setDiscount",
  "props": {
    "name": "MyDiscount",
    "value": 10,
    "scope": "sessionTotal",
    "desiredValue": 16
  }
}

Property	Type	Description
`name`	String	The name or description of this discount.
`value`	Number	The monetary value of the effective discount.
`scope`	String	What the discount applies to. Possible values: `cartItems`: Discount on the price of the items. `additionalCosts`: Discount on the additional costs of the items. `sessionTotal`: Discount on the total value of the customer session. note This property is not returned if cascading discounts are disabled in your Application.
`desiredValue`	Number	(Partial discounts enabled only) The monetary value of the discount to be applied without considering budget limitations.

setDiscountPerItem

This effect schema is returned when you use the Discount individual items, Discount individual items pro rata, or Discount individual item in bundles pro rata effect in a rule.

It indicates that a discount per item should be applied on the specific item specified in the effect.

The properties it contains depends on:

Whether you used a pro rata effect or not.
Whether you used an effect with bundles or not.
Whether the partial discount feature is enabled.

{
  ...
  "effectType": "setDiscountPerItem",
  "props": {
    "name": "10% off per item#1",
    "value": 10,
    "position": 1,
    "subPosition": 0,
    "desiredValue": 16,
    "totalDiscount": 10,
    "desiredTotalDiscount": 36,
    "scope": "price",
    "bundleIndex": 4,
    "bundleName": "Red pants",
    "targetedItemPosition": "1",
    "targetedItemSubPosition": "0"
  }
}

Property	Type	Description
`name`	String	The description of this discount. `#number` is equal to the `position` property.
`value`	Number	The monetary value of the effective discount applied to the item.
`position`	Number	The index of the item in the `cartItem` object on which this discount should be applied.
`subposition`	Number	The index of the item unit in its line item.
`desiredValue`	Number	(Partial discounts enabled only) The monetary value of the discount to be applied to the item without considering budget limitations.
`totalDiscount`	Number	(Pro rata discounts only) The monetary value of the total effective discount
`desiredTotalDiscount`	Number	(Pro rata discounts only) The monetary value of the total discount to be applied without considering budget limitations
`scope`	String	What the discount applies to. Possible values: `price`: discount on the price of the item. `additionalCosts`: discount on the additional cost of the item. `itemTotal`: discount on the sum of price + additional cost of the item.
`bundleIndex`	Integer	(Discounts with bundles only) The position of the specific item bundle in the list of bundles created from the same bundle definition.
`bundleName`	String	(Discounts with bundles only) The name of the bundle definition.
`targetedItemPosition`	Number	(Discounting individual item in bundles only) The index of the targeted bundle item on which the applied discount is based.
`targetedItemSubPosition`	Number	(Discounting individual item in bundles only) The sub-position of the targeted bundle item on which the applied discount is based.

If you use the Discount individual items effect in your rules and partial discounts is enabled, the rule passes even if the budget is insufficient to apply the full discount to every eligible cart item. In this case, one of the items in the list receives a lower discount and some items may receive no discount.

If you use the Discount bundles pro rata effect or the Discount individual items effect with a bundle definition as your list of cart items, use the bundleIndex and bundleName properties to identify the bundle whose items are discounted.

If the session contains some cart items with quantity > 1, use the subPosition property to identify the specific item unit in its line item. See the following example for more information:

Example: Discount individuals items

Let's imagine we want to discount individual items in the shoes category. Consider the following session:

Two cart items
The second cart item has a quantity of 2.

"cartItems": [
  {
    "name": "tshirt",
    "sku": "SKU3435",
    "quantity": 1,
    "price": 20,
    "category": "tshirts"
  },
  {
    "name": "Shoes1",
    "sku": "SKU1234",
    "quantity": 2,
    "price": 100,
    "category": "shoes"
  }
]

We have two items in the cart that are flattened into three items. We discount 2 items: the first pair of shoes, and the second one.

Flattened cart items
"cartItems": [
  {
    "name": "tshirt",
    "sku": "SKU3435",
    "quantity": 1,
    "price": 20,
    "category": "tshirts"
  },
  {
    "name": "Shoes1",
    "sku": "SKU1234",
    "quantity": 1,
    "price": 100,
    "category": "shoes"
  },
  {
    "name": "Shoes1",
    "sku": "SKU1234",
    "quantity": 1,
    "price": 100,
    "category": "shoes"
  }
]

A successful rule execution returns the following effects meaning the discount applies on the second cart item (position: 1 in the cart object), both units (subPosition 0 and 1):

{
  "effects": [
    {
      // ...
      "effectType": "setDiscountPerItem",
      "props": {
        "name": "10% off per item#1",
        "value": 10.0, // 10% of the flattened _line item_ price: 100
        "position": 1,
        "subPosition": 0 // first pair of shoes in the original cartItem object
      }
    },
    {
      // ...
      "effectType": "setDiscountPerItem",
      "props": {
        "name": "10% off per item#1",
        "value": 10.0, // 10% of the flattened _line item_ price: 100
        "position": 1,
        "subPosition": 1 // second pair of shoes in the original cartItem object
      }
    }
  ]
}

If you use a pro rata discount effect in your rules, use the totalDiscount property to identify the total value of the discount applied to all the items among which it is prorated. See the following example for more information:

Example: Pro rata discount

Let's imagine we want to issue a $30 pro rata discount among the three items in the cart.

"cartItems": [
  {
    "name": "tshirt",
    "sku": "SKU3435",
    "quantity": 1,
    "price": 20,
    "category": "tshirts",
  },
  {
    "name": "Shoes1",
    "sku": "SKU1234",
    "quantity": 1,
    "price": 40,
    "category": "shoes",
  },
  {
    "name": "Shoes2",
    "sku": "SKU0123",
    "quantity": 1,
    "price": 60,
    "category": "shoes",
  }
]

A successful rule execution returns the following effects:

{
  "effects": [
    {
      // ...
      "effectType": "setDiscountPerItem",
      "props": {
        "name": "25 pro rata",
        "value": 5,
        "position": 0,
        "totalDiscount": 30
      }
    },
    {
      // ...
      "effectType": "setDiscountPerItem",
      "props": {
        "name": "25 pro rata",
        "value": 10,
        "position": 1,
        "totalDiscount": 30
      }
    },
    {
      // ...
      "effectType": "setDiscountPerItem",
      "props": {
        "name": "25 pro rata",
        "value": 15,
        "position": 2,
        "totalDiscount": 30
      }
    }
  ]
}

If partial discounts is enabled and the budget is insufficient for the full discount to be applied, use the desiredTotalDiscount property to identify the original value of the total discount.

If you use the Discount individual item in bundles pro rata effect in your rules, use the targetedItemPosition and targetedItemSubPosition properties to identify the item on which the prorated discount is based. See the following example for more information:

Example: Discount individuals item in bundles

Let's imagine we want to give the tie for free to customers who buy a suit, shirt, and tie. Consider the following session:

Three cart items
One bundle definition

"cartItems": [
  {
    "name": "Suit",
    "sku": "SKU1044",
    "quantity": 1,
    "price": 190,
    "category": "suits"
  },
  {
    "name": "Shirt",
    "sku": "SKU3928",
    "quantity": 1,
    "price": 70,
    "category": "shirts"
  },
  {
    "name": "Tie",
    "sku": "SKU5113",
    "quantity": 1,
    "price": 25,
    "category": "accessories"
  }
]

A successful rule execution returns the following effect:

{
  "effects": [
    {
      // ...
      "effectType": "setDiscountPerItem",
      "props": {
        "name": "Free tie#0",
        "value": 16.67,
        "position": 0,
        "subPosition": 0,
        "totalDiscount": 25,
        "bundleIndex": 0,
        "bundleName": "Full_suit",
        "targetedItemPosition": 2,
        "targetedItemSubPosition": 0
      }
    },
    {
      // ...
      "effectType": "setDiscountPerItem",
      "props": {
        "name": "Free tie#1",
        "value": 6.14,
        "position": 1,
        "subPosition": 0,
        "totalDiscount": 25,
        "bundleIndex": 0,
        "bundleName": "Full_suit",
        "targetedItemPosition": 2,
        "targetedItemSubPosition": 0
      }
    },
    {
      // ...
      "effectType": "setDiscountPerItem",
      "props": {
        "name": "Free tie#2",
        "value": 2.19,
        "position": 2,
        "subPosition": 0,
        "totalDiscount": 25,
        "bundleIndex": 0,
        "bundleName": "Full_suit",
        "targetedItemPosition": 2,
        "targetedItemSubPosition": 0
      }
    }
  ]
}

addFreeItem

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.

{
  ...
  "effectType": "addFreeItem",
  "props": {
    "sku": "TEST-29372",
    "name": "Enjoy your free item"
  }
}

Property	Type	Description
`sku`	String	SKU of the item that needs to be added.
`name`	String	Description of the effect.

setDiscountPerAdditionalCost

It indicates that a discount that should be applied on a specific additional cost.

This gets triggered whenever a rule containing a Discount additional cost effect is validated.

{
  ...
  "effectType": "setDiscountPerAdditionalCost",
  "props": {
    "desiredValue": 5,
    "name": "50% off shipping cost",
    "additi
    "additionalCost": "shippingCost",
    "value": 2.5,
  }
}

Property	Type	Description
`desiredValue`	Number	(Partial discounts enabled only) The monetary value of the discount to be applied without considering budget limitations.
`name`	String	The name of the discount.
`additionalCostId`	Integer	The identifier of the additional cost.
`additionalCost`	String	The API name of the additional cost.
`value`	Number	The monetary value of the discount to apply.

setDiscountPerAdditionalCostPerItem

It indicates that a discount of a specific additional cost within a specific item should be applied.

This gets triggered whenever a rule containing a Discount additional cost per item effect is validated.

Use this effect when all items in the cart have an additional cost. If one of more items do not have an additional cost, the rule will fail.

{
  ...
  "effectType": "setDiscountPerAdditionalCostPerItem",
  "props": {
    "name": "10% off individual fee#1",
    "additionalCostId": 51,
    "additionalCost": "shippingCost",
    "value": 10,
    "position": 1,
    "subPosition": 0,
    "desiredValue": 16
  }
}

Property	Type	Description
`name`	String	The description of this discount. `#<number>` is appended to the name. It is equal to the `position` property.
`additionalCostId`	Integer	The identifier of the additional cost to be discounted.
`additionalCost`	String	The API name of the additional cost to be discounted.
`value`	Number	The monetary value of the effective discount applied to the item's additional cost.
`position`	Number	The index of the item in the `cartItem` object containing the additional cost that this discount applies to.
`subposition`	Number	The index of the item unit in its line item.
`desiredValue`	Number	(Partial discounts enabled only). The monetary value of the discount to be applied to the additional cost without considering budget limitations.

rollbackDiscount

It indicates that a discounted session, cart item, or additional cost has been cancelled or partially returned. This effect can only happen when you set the status of a session to cancel or the status changes to partially_returned.

If the session contains some cart items with quantity > 1, use the cartItemSubPosition property to identify the specific item unit in its line item. See the example below.

{
  ...
  "effectType": "rollbackDiscount",
  "props": {
    "name": "MyDiscount",
    "value": 10,
    "cartItemPosition": 1,
    "cartItemSubPosition": 0,
    "additionalCostId": 51,
    "additionalCost": "shippingCost",
    "scope": "itemTotal"
  }
}

Property	Type	Description
`name`	String	The name of the discount effect that was rolled back.
`value`	Number	The monetary value of the discount that was rolled back.
`cartItemPosition`	Number	The index of the item in the `cartItem` object whose discount was rolled back, or the unit containing the additional cost whose discount was rolled back.
`cartItemSubPosition`	Number	The index of the item unit in its line item for which the discount was rolled back.
`additionalCostId`	Number	Only when rolling back setDiscountPerAdditionalCost and setDiscountPerAdditionalCostPerItem The ID of the additional cost to be discounted.
`additionalCost`	String	The API name of the additional cost whose discount was rolled back.
`scope`	String	The scope of the rolled back discount. For a discount per session, it can be one of `cartItems`, `additionalCosts` or `sessionTotal` For a discount per item, it can be one of `price`, `additionalCosts` or `itemTotal`

Example

Let's imagine the customer wants to return a discounted pair of shoes, an item belonging to the shoes category. Consider the following session:

Two cart items.
The second cart item has a quantity of 2.

"cartItems": [
  {
    "name": "tshirt",
    "sku": "SKU3435",
    "quantity": 1,
    "price": 20,
    "category": "tshirts"
  },
  {
    "name": "shoes1",
    "sku": "SKU1234",
    "quantity": 2,
    "price": 100,
    "category": "shoes"
  }
]

Here, we split line items into units.

We have two items in the cart that are flattened into three items. We roll back the discount for 1 item: the first pair of shoes.

Representation of the cart
"cartItems": [
  {
    "name": "tshirt",
    "sku": "SKU3435",
    "quantity": 1,
    "price": 20,
    "category": "tshirts"
  },
  {
    "name": "Shoes1",
    "sku": "SKU1234",
    "quantity": 1,
    "price": 100,
    "category": "shoes"
  },
  {
    "name": "Shoes1",
    "sku": "SKU1234",
    "quantity": 1,
    "price": 100,
    "category": "shoes"
  }
]

A successful rule execution returns the following effects meaning the discount is rolled back for the second cart item (cartItemPosition: 1 in the cart object), first unit (cartItemSubPosition: 0):

{
  "effects": [
    {
      // ...
      "effectType": "rollbackDiscount",
      "props": {
        "name": "10% off per item#1",
        "value": 10.0, // 10% of the flattened _line item_ price: 100
        "cartItemPosition": 1,
        "cartItemSubPosition": 0 // first pair of shoes in the original cartItem object
      }
    }
  ]
}

Giveaways

These API effects are returned when you use a giveaway-reward effect.

AwardGiveaway
WillAwardGiveaway

awardGiveaway

It indicates the awarded giveaway item and to which profile the item was awarded. Learn more about giveaways.

{
  "effectType": "awardGiveaway",
  "props":
  {
    "poolId": 34,
    "poolName": "mypool",
    "recipientIntegrationId": "32hk597s-482y",
    "giveawayId": 45,
    "code": "9k849v-821o875"
  }
}

Property	Type	Description
`poolId`	Number	The internal ID of the giveaway pool.
`poolName`	String	The name of the giveaway pool.
`recipientIntegrationId`	String	The integration ID of the customer that receives the giveaway.
`giveawayId`	Number	The internal ID of the giveaway.
`code`	String	The giveaway code to be rewarded.

willAwardGiveaway

The equivalent of the awardGiveaway effect but returned when updating a session with any state other than closed. This ensures no giveaway codes are leaked when they are still not guaranteed to be awarded.

For more information about session states, see Managing states.

{
  "effectType": "willAwardGiveaway",
  "props": {
    "poolId": 34,
    "poolName": "mypool",
    "recipientIntegrationId": "32hk597s-482y"
  }
}

Property	Type	Description
`poolId`	Number	The internal ID of the giveaway pool.
`poolName`	String	The name of the giveaway pool.
`recipientIntegrationId`	String	The integration ID of the customer that receives the giveaway.

Loyalty

These API effects are returned when you use a loyalty-reward effect.

addLoyaltyPoints
deductLoyaltyPoints
rollbackAddedLoyaltyPoints
rollbackDeductedLoyaltyPoints
changeLoyaltyTierLevel

addLoyaltyPoints

It indicates that a defined amount of loyalty points was successfully added to the customer's profile or to a loyalty card.

If you use the Add loyalty points per item effect, use the cartItemPosition property to identify which item to add the loyalty points for.

Enabling partial rewards allows a rule that would fail because of insufficient budget to pass. The rule still fails when the budget reaches 0. Use the desiredValue property to identify the original amount of loyalty points.

If you use Add loyalty points per item and if the session contains some cart items with quantity > 1, use the cartItemSubPosition property to identify the item unit in its line item. See the example below for more information.

If your list of cart items is a bundle definition, use the bundleIndex and bundleName properties to identify the bundle containing the items for which loyalty points are added.

If you have set custom activation and expiration dates for the loyalty points, use the startDate and expiryDate properties to identify when the reward will be active and when will expire.

If the loyalty program is profile-based, use the recipientIntegrationId property to identify the user who receives the loyalty points. If the loyalty program is card-based, use the cardIdentifier property to identify the loyalty card on which these points are added.

important

The points only persist when the session is closed.

{
  ...
  "effectType": "addLoyaltyPoints",
  "props": {
    "name":"10% of current total",
    "programId": 302,
    "subLedgerId":"",
    "desiredValue": 4.50,
    "value":1.48,
    "recipientIntegrationId":"32hk597s-482y",
    "startDate": "2022-06-09T23:00:00+01:00",
    "expiryDate": "2022-06-23T23:00:00+01:00",
    "transactionUUID": "8828f4e0-d452-405b-94f2-5196125c54b4",
    "cartItemPosition": 1,
    "cartItemSubPosition": 0,
    "cardIdentifier": "identifier2045"
  }
}

Property	Type	Description
`name`	String	The reason of this loyalty point addition.
`programId`	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.
`desiredValue`	Number	(Partial rewards enabled only) The amount of loyalty points to be awarded without considering budget limitations.
`value`	Number	The amount of points that were added.
`recipientIntegrationId`	String	The user for whom these points were added.
`startDate`	String	The date after which the added points will be valid.
`expiryDate`	String	The date after which the added points will expire.
`transactionUUID`	String	The identifier of this loyalty points transaction.
`cartItemPosition`	Number	(Add points per cart item only.) The index of the item in the `cartItem` object for which these points were added.
`cartItemSubPosition`	Number	(Add points per cart item ) The index of the item unit in its line item.
`bundleIndex`	Integer	(With bundles only) The position of the specific bundle in the list of bundles created from the same bundle definition.
`bundleName`	String	(With bundles only) The name of the bundle definition.
`cardIdentifier`	String	The identifier of the card on which these points were added.

deductLoyaltyPoints

It indicates that the loyalty points a customer wanted to spend got subtracted from their loyalty wallet or their loyalty card.

This effect is generated when there is a Loyalty points in program Loyalty can be redeemed condition in an active campaign.

If the loyalty program is card-based, use the cardIdentifier property to identify the loyalty card from which these points are deducted.

important

The points only persist when the session is closed.

{
  ...
  "effectType": "deductLoyaltyPoints",
  "props": {
    "ruleTitle":"Cool-Summer!",
    "programId":1,
    "subLedgerId":"",
    "value":1,
    "transactionUUID": "06dc960c-ba56-45ff-996a-66c5ff5105et",
    "name":"Redeeming points according to offer",
    "cardIdentifier": "identifier2045"
  }
}

Property	Type	Description
`ruleTitle`	String	The title of the rule that contained triggered this points deduction.
`programId`	Integer	The ID of the loyalty program from which these points were deducted.
`subLedgerId`	String	The ID of the subledger within the loyalty program from which these points were deducted.
`value`	Number	The amount of points that were deducted.
`transactionUUID`	String	The identifier of this loyalty points transaction.
`cardIdentifier`	String	The identifier of the card from which these points were deducted.
`name`	String	The reason of this loyalty points deduction.

rollbackAddedLoyaltyPoints

It triggers in the following cases:

A session was cancelled in which loyalty points have been added.
A session was partially returned and loyalty point were added by the returned item(s). See returning items.

If you use the Add loyalty points per item effect, use the cartItemPosition property to identify which item(s) the loyalty points were rolled back for.

If you use Add loyalty points per item and if the session contains some cart items with quantity > 1, use the cartItemSubPosition property to identify the item unit in its line item.

If the loyalty program is profile-based, use the recipientIntegrationId property to identify the user for whom the loyalty points are rolled back. If the loyalty program is card-based, use the cardIdentifier property to identify the loyalty card where the points were originally added.

{
  ...
  "effectType": "rollbackAddedLoyaltyPoints",
  "props": {
    "programId": 302,
    "subLedgerId": "",
    "value": 1,
    "recipientIntegrationId": "32hk597s-482y",
    "transactionUUID": "76dc960c-ba56-45ff-996a-66c5ff5105ec",
    "cartItemPosition": 1,
    "cartItemSubPosition": 0,
    "cardIdentifier": "identifier2045"
  }
}

Property	Type	Description
`programId`	Integer	The ID of the loyalty program where these points were rolled back.
`subLedgerId`	String	The ID of the subledger within the loyalty program where these points were rolled back.
`value`	Number	The amount of points that were rolled back.
`recipientIntegrationId`	String	The user for whom these points were rolled back.
`transactionUUID`	String	The identifier of this loyalty points transaction.
`cartItemPosition`	Number	(Add points per cart item only.) The index of the item in the `cartItem` object for which these points were rolled back.
`cartItemSubPosition`	Number	(Add points per cart item ) The index of the item unit in its line item.
`cardIdentifier`	String	The identifier of the card on which these points were originally added.

rollbackDeductedLoyaltyPoints

It triggers in the following cases:

A session is cancelled and this session deducted loyalty points. The rollback action returns the redeemed loyalty points to the customer.
A session is impacted by a partial return. Only added loyalty points that are still pending are rolled back.
A session in which loyalty points were spent is reopened.

See the session states.

If you set custom activation and expiration dates for the loyalty points, use the startDate and expiryDate properties to identify when the reward will be active and when will expire.

{
  ...
  "effectType": "rollbackDeductedLoyaltyPoints",
  "props": {
    "programId": 327,
    "subLedgerId": "",
    "value": 1,
    "recipientIntegrationId": "32hk597s-482y",
    "startDate": "2022-06-09T23:00:00+01:00",
    "expiryDate": "2022-06-23T23:00:00+01:00",
    "transactionUUID": "06dc960c-ba56-45ff-996a-66c5ff5105et",
    "cardIdentifier": "identifier2045"
  }
}

Property	Type	Description
`programId`	Integer	The ID of the loyalty program where these points were reimbursed.
`subLedgerId`	String	The ID of the subledger within the loyalty program where these points were reimbursed.
`value`	Number	The amount of points that were reimbursed.
`recipientIntegrationId`	String	The user for whom these points were reimbursed.
`startDate`	String	The date after which the reimbursed points will be valid.
`expiryDate`	String	The date after which the reimbursed points will expire.
`transactionUUID`	String	The identifier of this loyalty points transaction.
`cardIdentifier`	String	The identifier of the card from which these points were originally deducted.

changeLoyaltyTierLevel

It indicates that a customer's loyalty tier has been upgraded.

This effect is generated only when the Add loyalty points and the Add loyalty points per cart item effects are triggered for a particular customer, and, as a result, the customer's loyalty tier is upgraded.

{
  ...
  "effectType": "changeLoyaltyTierLevel",
  "props": {
    "ruleTitle": "Reward customer",
    "programId": "1",
    "subledgerId": "",
    "previousTierName": "Silver",
    "newTierName": "Gold",
    "expiryDate": "2022-06-23T23:00:00+01:00",
  }
}

Property	Type	Description
`ruleTitle`	String	The title of the rule that triggered the tier upgrade.
`programId`	Integer	The ID of the loyalty program where the points were added.
`subledgerId`	Integer	The ID of the subledger within the loyalty program where the points were added.
`previousTierName`	String	The name of the tier from which the user was upgraded.
`newTierName`	String	The name of the tier to which the user has been upgraded.
`expiryDate`	String	The expiration date of the new tier.

Referrals

These API effects are returned when you use a referral effect.

referralCreated
rejectReferral
acceptReferral
redeemReferral (deprecated)
rollbackReferral

referralCreated

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

{
  ...
  "effectType": "referralCreated",
  "props": {
    "value": "ReferralCode"
  }
}

Property	Type	Description
`value`	String	The referral code provided in the session.

rejectReferral

Similar to rejectCoupon, but for referral codes. It indicates that the provided referral code is invalid.

{
  ...
  "effectType": "rejectReferral",
  "props": {
    "value": "2482-SUMMER-2022",
    "rejectionReason": "ReferralNotFound"
  }
}

Property Type Description

value String The referral code that was rejected

Property	Type	Description
`value`	String	The referral code that was rejected
`rejectionReason`	String	The reason why the code was rejected. `AdvocateNotFound`: The advocate was not found. `CampaignLimitReached`: The campaign-wide referral code redemption limit has been reached. `EffectCouldNotBeApplied`: One of the effects in the campaign wasn't applied because a limit for that effect was reached (most common use case will be `setDiscount` can not be applied because a discount limit is reached). `ProfileLimitReached`: The profile-specific referral code redemption limit has been reached. `ReferralCustomerAlreadyReferred`: The friend is already referred. `ReferralExpired`: The transferred referral code is expired. `ReferralLimitReached`: The referral code redemption limit has been reached. `ReferralNotFound`: The transferred referral code is wrong. `ReferralPartOfNotRunningCampaign`: The campaign the referral code belongs to is currently not active. The campaignId field shows the ID of that campaign. `ReferralRecipientDoesNotMatch`: The given referral code value does not match the recipient. `ReferralRecipientIdSameAsAdvocate`: The recipient (friend) has the same id as the advocate. `ReferralRejectedByCondition`: The referral code is valid and in an active campaign, but there were other conditions in that campaign's rules that were not met. `ReferralStartDateInFuture`: The transferred referral code isn't active yet. `ReferralPartOfNotTriggeredCampaign`: The campaign the referral code belongs to was not triggered during evaluation (an exclusive or stackable campaign). The campaignId field shows the ID of that campaign.
`campaignExclusionReason`	String	The reason why the campaign the referral belongs to was excluded during campaign evaluation, when `rejectionReason` was `CouponPartOfNotTriggeredCampaign`. Its possible values are: `CampaignGaveLowerDiscount`: The required campaign and referral conditions were met, but another campaign in a Highest discount value group offered a higher discount value. `CampaignIsNotFirst`: The campaign was not evaluated because another campaign in a First campaign group was picked and evaluated first. `CampaignNotInEvaluationSet`: The campaign did not meet other evaluation requirements.

rejectionReason

String

The reason why the code was rejected.

AdvocateNotFound: The advocate was not found.
CampaignLimitReached: The campaign-wide referral code redemption limit has been reached.
EffectCouldNotBeApplied: One of the effects in the campaign wasn't applied because a limit for that effect was reached (most common use case will be setDiscount can not be applied because a discount limit is reached).
ProfileLimitReached: The profile-specific referral code redemption limit has been reached.
ReferralCustomerAlreadyReferred: The friend is already referred.
ReferralExpired: The transferred referral code is expired.
ReferralLimitReached: The referral code redemption limit has been reached.
ReferralNotFound: The transferred referral code is wrong.
ReferralPartOfNotRunningCampaign: The campaign the referral code belongs to is currently not active. The campaignId field shows the ID of that campaign.
ReferralRecipientDoesNotMatch: The given referral code value does not match the recipient.
ReferralRecipientIdSameAsAdvocate: The recipient (friend) has the same id as the advocate.
ReferralRejectedByCondition: The referral code is valid and in an active campaign, but there were other conditions in that campaign's rules that were not met.
ReferralStartDateInFuture: The transferred referral code isn't active yet.
ReferralPartOfNotTriggeredCampaign: The campaign the referral code belongs to was not triggered during evaluation (an exclusive or stackable campaign). The campaignId field shows the ID of that campaign.

campaignExclusionReason

String

The reason why the campaign the referral belongs to was excluded during campaign evaluation, when rejectionReason was CouponPartOfNotTriggeredCampaign.
Its possible values are:

CampaignGaveLowerDiscount: The required campaign and referral conditions were met, but another campaign in a Highest discount value group offered a higher discount value.
CampaignIsNotFirst: The campaign was not evaluated because another campaign in a First campaign group was picked and evaluated first.
CampaignNotInEvaluationSet: The campaign did not meet other evaluation requirements.

acceptReferral

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.

The code is automatically redeemed when you close the session.

Other effects will provide more information about the actual reward.

{
  ...
  "effectType": "acceptReferral",
  "props": {
    "value": "Cool-Summer!"
  }
}

Property	Type	Description
`value`	String	The referral code provided in the session.

redeemReferral (deprecated)

note

This effect is deprecated. Talon.One sends an acceptReferral effect instead.

It indicates that the referral code is valid and has been redeemed. It triggers when a rule containing a redeem referral effect is validated.

{
  "effectType": "redeemReferral",
  "props": {
    "id": 43
    "value": "Cool-Summer!"
  }
}

Property	Type	Description
`value`	String	The referral code to redeem.

rollbackReferral

It indicates that the redemption of the referral code has been rolled back. It triggers when a closed session that redeemed a referral is gets cancelled. The code becomes redeemable again.

For more information about session states, see Managing states.

{
  ...
  "effectType": "rollbackReferral",
  "props": {
    "value": "Cool-Summer!"
  }
}

Property	Type	Description
`value`	String	The referral code to be rolled back.

Other

updateAttribute

It indicates that a rule containing an Update attribute value or Update cart item attribute value was validated. You should update the value of the attribute in your system based on the content of the returned effect.

{
 "effectType": "set",
 "props": {
     "path": "Session.Attributes.Airport_ID",
     "value": "CS-DG-02082021-UP-50G-07"
 }
}

Property	Type	Description
`path`	String	The entity type and the attribute name.
`value`	*	The new value of the attribute.

addToAudience

It is triggered when a rule containing an Update audience effect with Add customer to an audience selected is validated. It indicates that a customer was added to an audience and is returned when a customer session is opened, updated, or closed.

 {
  "effectType": "addToAudience",
  "props": {
      "audienceId": "10",
      "audienceName": "My audience",
      "profileIntegrationId": "URNGV8294NV",
      "profileId": "150"
  }
}

Property	Type	Description
`audienceId`	Integer	The internal ID of the audience.
`audienceName`	String	The name of the audience.
`profileIntegrationId`	String	The ID of the customer profile in the third-party integration platform.
`profileId`	Integer	The internal ID of the customer profile.

removeFromAudience

It is triggered when a rule containing an Update audience effect with Remove customer from an audience selected is validated. It indicates that a customer was removed from an audience and is returned when a customer session is opened, updated, or closed.

 {
  "effectType": "removeFromAudience",
  "props": {
      "audienceId": "10",
      "audienceName": "My audience",
      "profileIntegrationId": "URNGV8294NV",
      "profileId": "150"
  }
}

Property	Type	Description
`audienceId`	Integer	The internal ID of the audience.
`audienceName`	String	The name of the audience.
`profileIntegrationId`	String	The ID of the customer profile in the third-party integration platform.
`profileId`	Integer	The internal ID of the customer profile.

triggerWebhook

It is triggered when a rule containing a "trigger webhook" effect is validated. This effect is shared with you for your information only. It usually doesn't require an action on your side.

{
  "effectType": "triggerWebhook",
  "props" :{
    "webhookId": 234324.2352,
    "webhookName": "mywebhook"
  }
}

Property	Type	Description
`webhookId`	Integer	The internal ID of the webhook.
`webhookName`	String	The name of the webhook.

showNotification

You can use notifications to inform customers of certain events. There are four types of notification messages:

Info
Offer
Error
Misc

It is up to you to use the Rule Builder to decide why and when to show notifications. Notifications can be used as both rule effects and failure effects.

A common use case is to display the notification at the top of the cart view in your web app. You can use the notification type to vary the styling of the notification message.

{
  ...
  "effectType": "showNotification",
  "props": {
    "notificationType": "Error",
    "title": "An Error occurred",
    "body": "Please try again"
  }
}

Property	Type	Description
`notificationType`	String	The type of notification.
`title`	String	The title of the notification.
`body`	String	The body of the notification.

error

It is triggered whenever an error occurs during rule evaluation. This effect only provides information about what the error is.

{
  "effectType": "error",
  "props": {
    "message": "cannot rollback loyalty points that are not pending"
  }
}

Property	Type	Description
`message`	String	The error message.

Custom effects

The effects listed above are core effects provided by Talon.One. If you want to return data as an effect but no effect matches your use case, you can create a custom effect.

Custom effects can be used as both rule effects and failure effects.

{
 "effectType": "customEffect",
    "props": {
        // you define the properties
    }
}

The structure of a custom effect depends on your specifications but is always named customEffect.

Available rule effects

Locating the returned effects​

Interpreting the different effect types​

Achievements​

increaseAchievementProgress​

rollbackIncreasedAchievementProgress​

Coupons​

rejectCoupon​

acceptCoupon​

couponCreated​

rollbackCoupon​

reserveCoupon​

Discounts​

setDiscount​

setDiscountPerItem​

addFreeItem​

setDiscountPerAdditionalCost​

setDiscountPerAdditionalCostPerItem​

rollbackDiscount​

Giveaways​

awardGiveaway​

willAwardGiveaway​

Loyalty​

addLoyaltyPoints​

deductLoyaltyPoints​

rollbackAddedLoyaltyPoints​

rollbackDeductedLoyaltyPoints​

changeLoyaltyTierLevel​

Referrals​

referralCreated​

rejectReferral​

acceptReferral​

redeemReferral (deprecated)​

rollbackReferral​

Other​

updateAttribute​

addToAudience​

removeFromAudience​

triggerWebhook​

showNotification​

error​

Custom effects​

Related pages​

Locating the returned effects

Interpreting the different effect types

Achievements

increaseAchievementProgress

rollbackIncreasedAchievementProgress

Coupons

rejectCoupon

acceptCoupon

couponCreated

rollbackCoupon

reserveCoupon

Discounts

setDiscount

setDiscountPerItem

addFreeItem

setDiscountPerAdditionalCost

setDiscountPerAdditionalCostPerItem

rollbackDiscount

Giveaways

awardGiveaway

willAwardGiveaway

Loyalty

addLoyaltyPoints

deductLoyaltyPoints

rollbackAddedLoyaltyPoints

rollbackDeductedLoyaltyPoints

changeLoyaltyTierLevel

Referrals

referralCreated

rejectReferral

acceptReferral

redeemReferral (deprecated)

rollbackReferral

Other

updateAttribute

addToAudience

removeFromAudience

triggerWebhook

showNotification

error

Custom effects

Related pages