Effects
When KLP evaluates your campaigns, it returns the result as a list of effects. Each effect tells your system what to apply: a discount, a free item, a code, loyalty points, goal progress, and so on. The same effect contract is used by the Sessions, Events, consumer upsert and transaction search APIs (see Consumers, wallets and goals).
| Item | Value |
|---|---|
| APIs that return effects | Session, Event, Consumer Upsert and Transaction Search |
| Response envelope | effects[] + ruleFailureReasons[] |
| Dispatch key | actionType |
| Idempotency key | detail.effectTransactionId |
Rule engine result model
{
"effects": [
{
"campaignId": "4JC9YlDLJV30ysAKMbAc5w==",
"rulesetId": "cmCcAmKYV5FBUneZ5-8RZw==",
"ruleId": "a00834db-65fc-428e-a517-49c7c11ca74c",
"ruleName": "Campaign Rule",
"ruleIndex": 1,
"id": "50d68823-d217-4cfb-8bcd-29e9bfeb8d04",
"name": "Effect display name",
"actionType": "SetDiscount",
"detail": {
"effectTransactionId": "3a9f0bce-8900-4e6f-a263-e63c15243a6b",
"discount": {
"value": 23.25
}
}
}
],
"ruleFailureReasons": []
}
The result model can also contain optional fields. When they are null, they are omitted from the response:
| Field | Type | Description |
|---|---|---|
consumerProfile | object? | Consumer profile after rule evaluation |
triggeredCampaigns | array? | Triggered campaigns |
The result model can also contain an optional triggeredEvent field:
| Field | Type | Description |
|---|---|---|
triggeredEvent | string? | Name of the triggered event |
EffectResultModel fields
| Field | Type | Description |
|---|---|---|
campaignId | string? | Campaign identifier |
rulesetId | string | Ruleset identifier |
ruleId | Guid | Rule identifier |
ruleName | string? | Rule name |
ruleIndex | int | Rule index |
id | Guid? | Effect identifier |
name | string? | Effect name |
actionType | EffectActionType | Effect discriminator |
detail | RuleEngineEffectDetailModel? | Action-specific detail |
Treat identifier fields as opaque. Do not decode them or derive business meaning from them.
EffectActionType enum
The canonical enum values are:
SetDiscount
SetDiscountPerItem
GiveFreeItem
GiveVoucherCode
GiveCouponCode
RedeemCouponCode
GiveLoyaltyProgramPoints
RedeemLoyaltyProgramPoints
IncreaseGoalProgress
ShowInformation
GiveReferralCode
RedeemReferralCode
TriggerWebhook
UpdateAttribute
CustomEffect
CustomEffectPerItem
IncreaseMissionProgress
IncreaseLevelProgress
IncrementRewardClaimAmount
The last three values (IncreaseMissionProgress, IncreaseLevelProgress,
IncrementRewardClaimAmount) are gamification (mission, level and reward) effects. Their detail
models are not yet documented on this page. If you do not use gamification, you can safely ignore
these values through your Unknown fallback. The mission progress detail contains an optional
claimType field and a gameCompleted (bool) flag.
Naming note:
- For point operations,
actionTypeenum values are plural:GiveLoyaltyProgramPoints,RedeemLoyaltyProgramPoints. - The corresponding
detailproperties are singular:giveLoyaltyProgramPoint,redeemLoyaltyProgramPoint. - Singular action type values are not canonical. Do not accept them in your client enum.
Your client must not fail the whole response when it deserializes an unknown enum value. Provide
an Unknown fallback.
Common detail field
{
"effectTransactionId": "3a9f0bce-8900-4e6f-a263-e63c15243a6b"
}
effectTransactionId is a nullable Guid. When it is present, use it as the deduplication and audit
key. When it is null, use this fallback idempotency tuple:
application + integrationId + sessionId/event delivery ID + campaignId + ruleId + effect id
SetDiscount
{
"discount": {
"value": 23.25
}
}
discount.value is the order-level discount amount.
Client rules:
- Do not interpret the value as a percentage.
- Take the currency from the application context.
- Use decimal or fixed-point arithmetic.
- In the latest response for an Open session, replace the previous KLP order discount.
- Reject negative, NaN or overflow values.
SetDiscountPerItem
{
"discountPerItem": [
{
"value": 20.00,
"position": 0,
"itemParts": [
{
"value": 10.00,
"subPosition": 0,
"returned": false
},
{
"value": 10.00,
"subPosition": 1,
"returned": false
}
]
}
]
}
| Field | Type | Description |
|---|---|---|
value | double | Item discount total |
position | int | Original cart position |
itemParts | array | Quantity/bundle part breakdown |
itemParts[i].value | double | Part discount |
itemParts[i].subPosition | int | Part index |
itemParts[i].returned | bool | Whether the part has been refunded |
Your client must keep the mapping to the original cart positions. In a refund response, refunded
parts are marked returned: true.
GiveFreeItem
{
"giveFreeItem": {
"quantity": 1,
"sku": "NKTSH20240711"
}
}
The KLP response does not guarantee inventory availability. Your client applies its own stock, tax and fulfillment policy.
GiveVoucherCode
{
"giveVoucherCode": {
"poolId": "PV9dBPxnLuPh2DZ8U76OKw==",
"id": "voucher-id",
"code": "NETFLIXTHREE",
"expireDate": "2026-12-23T00:00:00Z",
"activationDate": "2026-07-07T09:32:50Z"
}
}
| Field | Nullable |
|---|---|
poolId | Yes |
id | Yes |
code | Yes |
expireDate | Yes |
activationDate | No |
Mask voucher codes in logs.
CouponCode (award and redeem)
GiveCouponCode and RedeemCouponCode use the same couponCode detail model.
{
"couponCode": {
"poolId": "693020781e6f892b14f691c1",
"lotId": "696a80b4743037e00bec124b",
"id": "coupon-id",
"code": "FWEPDFKLJQ97KB",
"expireDate": null,
"activationDate": "2026-02-16T14:50:04.007Z",
"type": "Award"
}
}
CodeEffectType:
Redeem
Award
Check that the action type and the type field are consistent.
Loyalty point award
Action type:
GiveLoyaltyProgramPoints
Detail property:
{
"giveLoyaltyProgramPoint": {
"organizationLoyaltyProgramId": "PV9dBPxnLuPh2DZ8U76OKw==",
"subLedger": "BasePoints",
"point": 7.75,
"reason": "Purchase reward",
"organizationConsumerIntegrationId": "consumer-id",
"organizationConsumerId": "1b40d8b5-36bf-4e9f-85a9-74b16e82769b",
"activationDate": "2026-08-01T00:00:00Z",
"expirationDate": "2027-08-01T00:00:00Z",
"transactionId": "1b40d8b5-36bf-4e9f-85a9-74b16e82769b",
"tier": {
"tierId": "HPSUCwHh4FSxXlmlsCqfiA==",
"tierLevelId": "26275059-d1fa-4290-82b1-591b70ee9aea",
"nextEvaluationDate": "2026-09-05T06:52:25Z",
"progress": 7.75
}
}
}
The award detail includes:
organizationConsumerIntegrationIdorganizationConsumerId- Optional
tier
Points and tier progress are decimals.
Loyalty point redeem
Action type:
RedeemLoyaltyProgramPoints
{
"redeemLoyaltyProgramPoint": {
"organizationLoyaltyProgramId": "PV9dBPxnLuPh2DZ8U76OKw==",
"subLedger": "BasePoints",
"point": 150.00,
"reason": "Checkout redemption",
"transactionId": "2a51a9c5-42de-9a6e-8f4c-12a56e71354a",
"tier": {
"tierId": "HPSUCwHh4FSxXlmlsCqfiA==",
"tierLevelId": "26275059-d1fa-4290-82b1-591b70ee9aea",
"nextEvaluationDate": "2026-09-05T06:52:25Z",
"progress": 100.00
}
}
}
The redeem model can also contain optional tier information.
Point effect history enum:
Redeem
Award
Expire
IncreaseGoalProgress
{
"increaseGoalProgress": {
"goalId": "WoIl2IoXT_dplrE1KbuPjA==",
"organizationConsumerGoalId": "69931f5e2b5e9e5b5104efea",
"value": 10,
"total": 10,
"target": 100,
"completed": false,
"startDate": "2026-02-16T16:45:02.6436468Z",
"endDate": "2026-03-14T00:00:00"
}
}
Treat completed as the source of truth. Do not derive completion on the client only from
total >= target.
ShowInformation
{
"showInformation": {
"value": "You're close to the next benefit."
}
}
value is typed string?.
Your client can treat this value as a display-ready message. Apply your localization and HTML escaping policy.
ReferralCode (award and redeem)
GiveReferralCode and RedeemReferralCode use the same detail model:
{
"referralCode": {
"poolId": "6908555e5308cd2540202ae3",
"id": "referral-id",
"code": "VLUJQ8LD",
"expireDate": null,
"type": "Award"
}
}
Referral codes are sensitive benefits. Mask them in logs.
TriggerWebhook
{
"triggerWebhook": {
"webhookId": "webhook-id",
"attributes": {
"ConsumerId": "consumer-id"
},
"parameters": {
"CampaignId": "campaign-id"
}
}
}
| Field | Type |
|---|---|
webhookId | string |
attributes | Dictionary<string, object> |
parameters | Dictionary<string, string> |
attributes values are typed: they can be a string, number, boolean or nested JSON. Do not assume
they are strings.
This effect is the result of a webhook that KLP has already executed server-side. Do not trigger the webhook a second time from your client; you can only audit the result.
UpdateAttribute
{
"updateAttribute": {
"attributeId": "attribute-id",
"attributeKey": "PurchaseCount",
"operatorType": "IncreaseBy",
"value": "1"
}
}
Operator enum:
SetToValue
IncreaseBy
DecreaseBy
MultiplyBy
DivideBy
value is carried as a string. Parse it according to the attribute's type metadata.
CustomEffect
{
"customEffect": {
"id": "custom-effect-id",
"apiName": "GrantPartnerBenefit",
"payload": "{\"benefitId\":\"123\"}"
}
}
payload is a string and is not required to be JSON. Your custom effect handler should:
- Apply an
apiNameallow-list. - Enforce a payload size limit.
- Validate the schema and version.
- Quarantine unknown custom effects.
CustomEffectPerItem
{
"customEffectPerItem": {
"id": "custom-effect-id",
"apiName": "ItemBenefit",
"items": [
{
"position": 0,
"itemParts": [
{
"subPosition": 0,
"payload": "{\"value\":10}",
"returned": false
}
]
}
]
}
}
Handle the item position/sub-position mapping and the returned flag together with your refund
logic.
RuleFailureReasons model
{
"ruleFailureReasons": [
{
"campaignId": "campaign-id",
"rulesetId": "ruleset-id",
"details": [
{
"ruleId": "rule-id",
"ruleName": "Rule",
"ruleIndex": 2,
"couponId": null,
"referralId": null,
"type": "Condition",
"index": 1,
"message": ""
}
]
}
]
}
| Field | Type |
|---|---|
campaignId | Declared as long?; examples can contain an encrypted string |
rulesetId | string |
details | array |
ruleId | Guid? |
ruleName | string? |
ruleIndex | int? |
couponId | string? |
referralId | string? |
type | RuleFailureReasonType |
index | int? |
message | string? |
Because the declared type and the actual values of campaignId differ, use an opaque,
string-compatible serializer for it.
RuleFailureReasonType:
Condition
Effect
Limit
Session
System
Cancel
Business failures can be returned inside an HTTP 200 response.
Cancel and refund effect matrix
Reversible on cancel
These effects are listed as reversible when a session is cancelled (see Cancel session in Sessions):
RedeemCouponCode
GiveCouponCode
GiveVoucherCode
GiveLoyaltyProgramPoints
RedeemLoyaltyProgramPoints
IncreaseGoalProgress
A successful cancel response can also return SetDiscountPerItem. This list is not exhaustive;
build your own production test matrix.
Refundable
SetDiscountPerItem
CustomEffectPerItem
Refunded item parts are marked:
"returned": true
Effect processor design
for effect in response.effects:
validate common fields
if effectTransactionId exists and already processed:
skip
handler = registry.find(effect.actionType)
if handler missing:
log + quarantine/ignore by policy
continue
normalizedCommand = handler.validateAndMap(effect)
apply normalizedCommand
persist audit/idempotency state
Handlers should not spread the transport DTO directly into your checkout model. Have them produce an internal normalized command instead.
Latest response semantics
For Open session updates, treat the latest effect set as the result of the current snapshot (see Sessions).
Recommended order:
- Identify the previous provisional KLP adjustments.
- Remove the previous result set.
- Validate the latest effects.
- Apply them in a deterministic order.
- Update the audit and idempotency state.
Appending effects incrementally risks a double discount or a duplicate free item.
Unknown and malformed effect handling
| Case | Behavior |
|---|---|
Unknown actionType | Do not fail the whole response; log/quarantine |
| Missing expected detail | Effect-level validation failure |
Null effectTransactionId | Fallback deduplication tuple |
| Negative discount/point | Reject + alert |
| Item position not found | Do not apply; raise a reconciliation alarm |
| Duplicate effect | Deduplicate |
| Invalid date | Do not apply the sensitive reward; send to error queue |
| Unknown code/status enum | Forward-compatible fallback |
| Invalid custom payload | Quarantine |
Observability
Metrics:
- Request latency and HTTP status distribution
- Effects per
actionType - Rule failures per
type - Unknown effect count
- Duplicate effect count
- Effect apply failures
- Cancel/refund success and business conflicts
- Reconciliation mismatches
- Rate-limit
429responses
Log fields:
- Environment/application
- Correlation ID
- Masked/hashed
integrationId sessionIdcampaignIdruleIdactionTypeeffectTransactionId
Do not log API keys, JWTs, coupon/voucher/referral codes or PII.
Contract test checklist
- Every EffectActionType deserializes
- Plural naming of point action types is verified
- Unknown action type fallback
- Missing detail validation
- Decimal precision
- SetDiscount replacement semantics
- Item position/sub-position mapping
- Returned item part mapping
- Duplicate effect deduplication
- Null effectTransactionId fallback
- Voucher activation/expiration parsing
- Coupon
lotId - Loyalty consumer IDs
- Optional tier on award
- Optional tier on redeem
- Goal organizationConsumerGoalId/start/end
- ShowInformation string value
- TriggerWebhook model
- UpdateAttribute operator enum
- CustomEffect payload validation
- CustomEffectPerItem refund behavior
- Empty effects are valid
- HTTP 200 with rule failures
- CampaignId type inconsistency handling
- Cancel reversible effect matrix
- Refund effect matrix