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 web app, 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.

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

Interpret the different effect types

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

Achievements

increaseAchievementProgress

This effect indicates that the customer's progress in an achievement was updated during the current session. It is triggered when a rule using the Update customer progress effect is successfully validated.

For on-completion achievements, any customer progress exceeding the target automatically starts a new iteration. This generates a new progressTrackerId for each iteration, and there can be multiple progress updates for the same achievement from a single validation of this effect.

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

Property	Type	Description	Required
`achievementId`	Integer	The internal ID of the achievement.	Yes
`achievementName`	String	The name of the achievement.	Yes
`progressTrackerId`	Integer	The internal ID of the customer progress tracker.For on-completion achievements, this effect generates a unique ID for each iteration.	No
`delta`	Number	The value by which the customer's current progress in the achievement has increased.	Yes
`value`	Number	The current progress of the customer in the achievement.	Yes
`target`	Number	The target value to complete the achievement.	Yes
`isJustCompleted`	Boolean	Indicates if the customer has completed the achievement in the current session.	Yes

rollbackIncreasedAchievementProgress

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

The Rule Engine triggers this effect when you cancel or reopen a customer session that previously validated the Update customer progress effect and triggered the increaseAchievementProgress API effect.

The effect is also triggered for completed achievements if the Allow progress rollback for completed achievements setting is enabled. You can enable this through the Campaign Manager or the Management API by setting the achievementAllowRollbackAfterCompletion property to true. This setting only applies to one-time and recurring on expiration achievements.

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

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

Coupons

acceptCoupon

This effect 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": "COUP-XYZ789"
  }
}

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

couponCreated

This effect 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": "COUP-NEW123",
    "profileId": "customer_profile_id_1"
  }
}

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

rejectCoupon

This effect 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": "COUP-XYZ789",
    "rejectionReason": "CouponRejectedCondition",
    "conditionIndex": 2,
    "effectIndex": 0,
    "details": "Coupon usage limit reached",
    "campaignExclusionReason": "CampaignGaveLowerDiscount"
  }
}

Property	Type	Description	Required
`value`	String	The coupon code that was rejected.	Yes
`rejectionReason`	String	The reason why the code was rejected. `CampaignLimitReached`: The campaign-wide coupon code redemption limit has been reached. `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.	Yes
`conditionIndex`	Integer	The index of the condition that caused the rejection of the coupon.	No
`effectIndex`	Integer	The index of the effect that caused the rejection of the coupon.	No
`details`	String	More details about the failure.	No
`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, for example, because the coupon is part of an archived campaign.	No

reserveCoupon

This effect indicates that the given coupon code was reserved for the given customer.

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

{
  "effectType": "reserveCoupon",
  "props": {
    "couponValue": "COUP-XYZ789",
    "profileIntegrationId": "customer_profile_id_1",
    "isNewReservation": true
  }
}

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

rollbackCoupon

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

The effect is triggered 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": "COUP-XYZ789"
  }
}

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

Discounts

addFreeItem

This effect 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.

The effect of a successful referral can mean a free item for someone else, such as the referrer.

{
  "effectType": "addFreeItem",
  "props": {
    "sku": "SKU1241028",
    "name": "Free Gift Item",
    "desiredQuantity": 1
  }
}

Property	Type	Description	Required
`sku`	String	SKU of the item that needs to be added.	Yes
`name`	String	Description of the effect.	Yes
`desiredQuantity`	Integer	The original quantity in case a partial reward was applied.	No

rollbackDiscount

This effect 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": "10% Off",
    "value": 2.5,
    "cartItemPosition": 1,
    "cartItemSubPosition": 1,
    "additionalCostId": 1,
    "additionalCost": "shipping",
    "scope": "sessionTotal"
  }
}

Property	Type	Description	Required
`name`	String	The name of the discount effect that was rolled back.	Yes
`value`	Number	The monetary value of the discount that was rolled back.	Yes
`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.	No
`cartItemSubPosition`	Number	The index of the item unit in its line item for which the discount was rolled back.	No
`additionalCostId`	Integer	Only when rolling back setDiscountPerAdditionalCost and setDiscountPerAdditionalCostPerItem The ID of the additional cost to be discounted.	No
`additionalCost`	String	The API name of the additional cost whose discount was rolled back.	No
`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`	No

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

setDiscount

This effect indicates that a discount should be set on the total shopping cart value of the current order with the given label and amount.

The 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": "10% Off",
    "value": 2.5,
    "scope": "sessionTotal",
    "desiredValue": 2.5
  }
}

Property	Type	Description	Required
`name`	String	The name or description of this discount.	Yes
`value`	Number	The monetary value of the effective discount.	Yes
`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: Cascading discounts must be enabled for this property to be returned.	No
`desiredValue`	Number	(Partial discounts enabled only) The monetary value of the discount to be applied without considering budget limitations.	No

setDiscountPerAdditionalCost

This effect indicates that a discount that should be applied on a specific additional cost. It is triggered whenever a rule containing a Discount additional cost effect is validated.

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.

{
  "effectType": "setDiscountPerAdditionalCost",
  "props": {
    "name": "Shipping discount",
    "additionalCostId": 1,
    "additionalCost": "shipping",
    "value": 4.99,
    "desiredValue": 4.99
  }
}

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

setDiscountPerAdditionalCostPerItem

This effect indicates that a discount of a specific additional cost within a specific item should be applied. It 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": "Shipping discount on item #1",
    "additionalCostId": 1,
    "value": 4.99,
    "position": 1,
    "subPosition": 1,
    "additionalCost": "shipping",
    "desiredValue": 4.99
  }
}

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

setDiscountPerItem

This effect schema is returned when you use the Discount individual items, Discount individual items pro rata, or Discount individual item in bundles 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": "Discount on item #1",
    "value": 1.5,
    "position": 1,
    "subPosition": 1,
    "desiredValue": 1.5,
    "scope": "price",
    "totalDiscount": 1.5,
    "desiredTotalDiscount": 1.5,
    "bundleIndex": 1,
    "bundleName": "my_bundle",
    "targetedItemPosition": 1,
    "targetedItemSubPosition": 1,
    "excludedFromPriceHistory": false
  }
}

Property	Type	Description	Required
`name`	String	The description of this discount. `#number` is equal to the `position` property.	Yes
`value`	Number	The monetary value of the effective discount applied to the item.	Yes
`position`	Number	The index of the item in the `cartItem` object on which this discount should be applied.	Yes
`subPosition`	Number	The index of the item unit in its line item.	No
`desiredValue`	Number	(Partial discounts enabled only) The monetary value of the discount to be applied to the item without considering budget limitations.	No
`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.	No
`totalDiscount`	Number	(Pro rata discounts only) The monetary value of the total effective discount	No
`desiredTotalDiscount`	Number	(Pro rata discounts only) The monetary value of the total discount to be applied without considering budget limitations	No
`bundleIndex`	Integer	(Discounts with bundles only) The position of the specific item bundle in the list of bundles created from the same bundle definition.	No
`bundleName`	String	(Discounts with bundles only) The name of the bundle definition.	No
`targetedItemPosition`	Number	(Discounting individual item in bundles only) The index of the targeted bundle item on which the applied discount is based.	No
`targetedItemSubPosition`	Number	(Discounting individual item in bundles only) The sub-position of the targeted bundle item on which the applied discount is based.	No
`excludedFromPriceHistory`	Boolean	When set to `true`, the applied discount is excluded from the item's price history.	No

If you use the Discount individual items effect in your rules after enabling partial discounts, 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 you enabled partial discounts, you can use the desiredTotalDiscount property to identify the original value of the total discount when the budget is insufficient for the full discount to be applied.

If you use the Discount individual item in bundles effect in your rules and choose to apply the discount pro rata, 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
      }
    }
  ]
}

Giveaways

awardGiveaway

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

{
  "effectType": "awardGiveaway",
  "props": {
    "poolId": 2,
    "poolName": "My pool",
    "recipientIntegrationId": "URNGV8294NV",
    "giveawayId": 5,
    "code": "57638t-67439hty"
  }
}

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

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 Manage the session's state.

{
  "effectType": "willAwardGiveaway",
  "props": {
    "poolId": 2,
    "poolName": "My pool",
    "recipientIntegrationId": "URNGV8294NV"
  }
}

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

Loyalty

addLoyaltyPoints

This effect 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.

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.

The points only persist when the session is closed.

{
  "effectType": "addLoyaltyPoints",
  "props": {
    "name": "Points for purchase",
    "programId": 5,
    "subLedgerId": "main",
    "value": 100,
    "desiredValue": 100,
    "recipientIntegrationId": "URNGV8294NV",
    "startDate": "2024-01-01T00:00:00.000Z",
    "expiryDate": "2025-01-01T00:00:00.000Z",
    "transactionUUID": "8c2d3670-6ea5-4e9e-b5c6-e7e7b4a10111",
    "cartItemPosition": 1,
    "cartItemSubPosition": 1,
    "cardIdentifier": "loyalty-card-001",
    "bundleIndex": 1,
    "bundleName": "my_bundle",
    "awaitsActivation": false,
    "validityDuration": "12M"
  }
}

Property	Type	Description	Required
`name`	String	The reason of this loyalty point addition.	Yes
`programId`	Integer	The ID of the loyalty program where these points were added.	Yes
`subLedgerId`	String	The ID of the subledger within the loyalty program where these points were added.	Yes
`value`	Number	The amount of points that were added.	Yes
`desiredValue`	Number	(Partial rewards enabled only) The amount of loyalty points to be awarded without considering budget limitations.	No
`recipientIntegrationId`	String	The user for whom these points were added.	Yes
`startDate`	String	The date after which the added points will be valid.	No
`expiryDate`	String	The date after which the added points will expire.	No
`transactionUUID`	String	The identifier of this loyalty point transaction.	Yes
`cartItemPosition`	Number	(Add points per cart item only.) The index of the item in the `cartItem` object for which these points were added.	No
`cartItemSubPosition`	Number	(Add points per cart item ) The index of the item unit in its line item.	No
`cardIdentifier`	String	The identifier of the card on which these points were added.	No
`bundleIndex`	Integer	(With bundles only) The position of the specific bundle in the list of bundles created from the same bundle definition.	No
`bundleName`	String	(With bundles only) The name of the bundle definition.	No
`awaitsActivation`	Boolean	Indicates whether the points have an action-based start date. This property is returned only for point transactions with an action-based start date.	No
`validityDuration`	String	The duration for which the points remain active, calculated relative to their start date.	No

changeLoyaltyTierLevel

This effect 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": "Tier upgrade on purchase",
    "programId": 5,
    "subLedgerId": "main",
    "previousTierName": "Silver",
    "newTierName": "Gold",
    "expiryDate": "2025-12-31T23:59:59.000Z"
  }
}

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

deductLoyaltyPoints

This effect is triggered when a customer redeems loyalty points. The points are deducted from their active point balance.

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

The Rule Engine deducts points in this order:

Points with the earliest expiry date are deducted first, regardless of when they were added.
Points with an unlimited expiry date are deducted last.
For points with an unlimited expiry date, the points awarded first are deducted first.

The points only persist when the session is closed.

{
  "effectType": "deductLoyaltyPoints",
  "props": {
    "ruleTitle": "Deduct points on return",
    "programId": 5,
    "subLedgerId": "main",
    "value": 50,
    "transactionUUID": "9f3e4781-7fb6-5f0f-c6d7-f8f8c5b21222",
    "name": "Points deducted for return",
    "cardIdentifier": "loyalty-card-001"
  }
}

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

extendLoyaltyPointsExpiryDate

If loyalty points have an expiry date, this effect extends the expiry of all active and pending point transactions by a selected duration.

{
  "effectType": "extendLoyaltyPointsExpiryDate",
  "props": {
    "programId": 5,
    "subLedgerId": "main",
    "extensionDuration": "12h",
    "affectedTransactions": []
  }
}

Property	Type	Description	Required
`programId`	Integer	ID of the loyalty program that contains these points.	Yes
`subLedgerId`	String	API name of the loyalty program subledger that contains these points.	Yes
`extensionDuration`	String	Time frame by which the expiry date extends. The time format is either: immediate, or an integer followed by a letter indicating the time unit. Examples: `immediate`, `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`. Available units: `s`: seconds `m`: minutes `h`: hours `D`: days `W`: weeks `M`: months `Y`: years You can round certain units up or down: `_D` for rounding down days only. Signifies the start of the day. `_U` for rounding up days, weeks, months and years. Signifies the end of the day, week, month or year.	Yes
`affectedTransactions`	Array	List of transactions affected by the expiry date update.	No

rollbackAddedLoyaltyPoints

This effect is triggered 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 items. See returning items.

If you use the Add loyalty points per item effect, use the cartItemPosition property to identify which items 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": 5,
    "subLedgerId": "main",
    "value": 100,
    "recipientIntegrationId": "URNGV8294NV",
    "transactionUUID": "8c2d3670-6ea5-4e9e-b5c6-e7e7b4a10111",
    "cartItemPosition": 1,
    "cartItemSubPosition": 1,
    "cardIdentifier": "loyalty-card-001"
  }
}

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

rollbackDeductedLoyaltyPoints

This effect is triggered 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": 5,
    "subLedgerId": "main",
    "value": 50,
    "recipientIntegrationId": "URNGV8294NV",
    "startDate": "2024-01-01T00:00:00.000Z",
    "expiryDate": "2025-01-01T00:00:00.000Z",
    "transactionUUID": "9f3e4781-7fb6-5f0f-c6d7-f8f8c5b21222",
    "cardIdentifier": "loyalty-card-001"
  }
}

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

setLoyaltyPointsExpiryDate

This effect updates the expiry date of all active, pending, and unlimited point transactions to a specific date.

{
  "effectType": "setLoyaltyPointsExpiryDate",
  "props": {
    "programId": 5,
    "subLedgerId": "main",
    "newExpiryDate": "2024-07-24T14:15:22.000Z",
    "affectedTransactions": []
  }
}

Property	Type	Description	Required
`programId`	Integer	ID of the loyalty program that contains these points.	Yes
`subLedgerId`	String	API name of the loyalty program subledger that contains these points.	Yes
`newExpiryDate`	String	The specified expiry date and time for all active and pending point transactions in the loyalty program subledger.	Yes
`affectedTransactions`	Array	List of transactions affected by the expiry date update.	No

Referrals

acceptReferral

This effect 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": "REF-ABC123"
  }
}

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

redeemReferral

This effect is deprecated. It has been replaced by the acceptReferral effect. This effect indicates that the referral code is valid and has been redeemed.

{
  "effectType": "redeemReferral",
  "props": {
    "id": 12,
    "value": "REF-ABC123"
  }
}

Property	Type	Description	Required
`id`	Integer	The id of the referral code that was redeemed.	Yes
`value`	String	The referral code that was redeemed.	Yes

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": "REF-NEW456"
  }
}

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

rejectReferral

This effect indicates that the provided referral code is invalid.

{
  "effectType": "rejectReferral",
  "props": {
    "value": "REF-ABC123",
    "rejectionReason": "ReferralRejectedCondition",
    "conditionIndex": 1,
    "effectIndex": 0,
    "details": "Referral code already used",
    "campaignExclusionReason": "CampaignGaveLowerDiscount"
  }
}

Property	Type	Description	Required
`value`	String	The referral code that was rejected	Yes
`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 campaign ID 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 campaign ID field shows the ID of that campaign.	Yes
`conditionIndex`	Integer	The index of the condition that caused the rejection of the referral.	No
`effectIndex`	Integer	The index of the effect that caused the rejection of the referral.	No
`details`	String	More details about the failure.	No
`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, for example, because the referral is part of an archived campaign.	No

rollbackReferral

This effect 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": "REF-ABC123"
  }
}

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

Other

addToAudience

This effect 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	Required
`audienceId`	Integer	The internal ID of the audience.	No
`audienceName`	String	The name of the audience.	No
`profileIntegrationId`	String	The ID of the customer profile in the third-party integration platform.	No
`profileId`	Integer	The internal ID of the customer profile.	No

customEffect

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.

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

{
  "effectType": "customEffect",
  "props": {
    "effectId": 1,
    "name": "my_custom_effect",
    "cartItemPosition": 1,
    "cartItemSubPosition": 2,
    "bundleIndex": 1,
    "bundleName": "my_bundle",
    "payload": {
      "key": "value"
    }
  }
}

Property	Type	Description	Required
`effectId`	Integer	The ID of the custom effect that was triggered.	Yes
`name`	String	The type of the custom effect.	Yes
`cartItemPosition`	Number	The index of the item in the cart item list to which the custom effect is applied.	No
`cartItemSubPosition`	Number	For cart items with quantity > 1, the sub position indicates to which item unit the custom effect is applied.	No
`bundleIndex`	Integer	The position of the bundle in a list of item bundles created from the same bundle definition.	No
`bundleName`	String	The name of the bundle definition.	No
`payload`	Object	The JSON payload of the custom effect.	Yes

error

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

{
  "effectType": "error",
  "props": {
    "message": "An unexpected error occurred during rule evaluation."
  }
}

Property	Type	Description	Required
`message`	String	The error message.	Yes

removeFromAudience

This effect 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	Required
`audienceId`	Integer	The internal ID of the audience.	No
`audienceName`	String	The name of the audience.	No
`profileIntegrationId`	String	The ID of the customer profile in the third-party integration platform.	No
`profileId`	Integer	The internal ID of the customer profile.	No

showBundleMetadata

This effect is deprecated.

The ShowBundleMetadata effect contains information that allows you to associate the discounts from a rule in a bundle campaign with specific cart items. This way you can distinguish from "normal" discounts that were not the result of a product bundle.

{
  "effectType": "showBundleMetadata",
  "props": {
    "description": "Buy 2 get 1 free bundle",
    "bundleAttributes": [
      "category",
      "brand"
    ],
    "itemsIndices": [
      0,
      1,
      2
    ]
  }
}

Property	Type	Description	Required
`description`	String	Description of the product bundle.	Yes
`bundleAttributes`	Array	The cart item attributes that determined which items are being bundled together.	Yes
`itemsIndices`	Array	The indices in the cart items array of the bundled items.	Yes

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": "info",
    "title": "Discount applied",
    "body": "You have received a 10% discount on your order."
  }
}

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

triggerWebhook

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

{
  "effectType": "triggerWebhook",
  "props": {
    "webhookId": 7,
    "webhookName": "My Webhook"
  }
}

Property	Type	Description	Required
`webhookId`	Number	The internal ID of the webhook.	Yes
`webhookName`	String	The name of the webhook.	Yes

updateAttribute

This effect 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": "updateAttribute",
  "props": {
    "path": "Session.Attributes.loyaltyTier",
    "value": "Gold"
  }
}

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

Available rule effects

Locate the returned effects​

Interpret the different effect types​

Achievements​

increaseAchievementProgress​

rollbackIncreasedAchievementProgress​

Coupons​

acceptCoupon​

couponCreated​

rejectCoupon​

reserveCoupon​

rollbackCoupon​

Discounts​

addFreeItem​

rollbackDiscount​

setDiscount​

setDiscountPerAdditionalCost​

setDiscountPerAdditionalCostPerItem​

setDiscountPerItem​

Giveaways​

awardGiveaway​

willAwardGiveaway​

Loyalty​

addLoyaltyPoints​

changeLoyaltyTierLevel​

deductLoyaltyPoints​

extendLoyaltyPointsExpiryDate​

rollbackAddedLoyaltyPoints​

rollbackDeductedLoyaltyPoints​

setLoyaltyPointsExpiryDate​

Referrals​

acceptReferral​

redeemReferral​

referralCreated​

rejectReferral​

rollbackReferral​

Other​

addToAudience​

customEffect​

error​

removeFromAudience​

showBundleMetadata​

showNotification​

triggerWebhook​

updateAttribute​

Related pages​