Skip to main content

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

ItemValue
APIs that return effectsSession, Event, Consumer Upsert and Transaction Search
Response envelopeeffects[] + ruleFailureReasons[]
Dispatch keyactionType
Idempotency keydetail.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:

FieldTypeDescription
consumerProfileobject?Consumer profile after rule evaluation
triggeredCampaignsarray?Triggered campaigns
Pending verification

The result model can also contain an optional triggeredEvent field:

FieldTypeDescription
triggeredEventstring?Name of the triggered event

EffectResultModel fields​

FieldTypeDescription
campaignIdstring?Campaign identifier
rulesetIdstringRuleset identifier
ruleIdGuidRule identifier
ruleNamestring?Rule name
ruleIndexintRule index
idGuid?Effect identifier
namestring?Effect name
actionTypeEffectActionTypeEffect discriminator
detailRuleEngineEffectDetailModel?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
Pending verification

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, actionType enum values are plural: GiveLoyaltyProgramPoints, RedeemLoyaltyProgramPoints.
  • The corresponding detail properties 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
}
]
}
]
}
FieldTypeDescription
valuedoubleItem discount total
positionintOriginal cart position
itemPartsarrayQuantity/bundle part breakdown
itemParts[i].valuedoublePart discount
itemParts[i].subPositionintPart index
itemParts[i].returnedboolWhether 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"
}
}
FieldNullable
poolIdYes
idYes
codeYes
expireDateYes
activationDateNo

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:

  • organizationConsumerIntegrationId
  • organizationConsumerId
  • 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"
}
}
}
FieldType
webhookIdstring
attributesDictionary<string, object>
parametersDictionary<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 apiName allow-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": ""
}
]
}
]
}
FieldType
campaignIdDeclared as long?; examples can contain an encrypted string
rulesetIdstring
detailsarray
ruleIdGuid?
ruleNamestring?
ruleIndexint?
couponIdstring?
referralIdstring?
typeRuleFailureReasonType
indexint?
messagestring?

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:

  1. Identify the previous provisional KLP adjustments.
  2. Remove the previous result set.
  3. Validate the latest effects.
  4. Apply them in a deterministic order.
  5. Update the audit and idempotency state.

Appending effects incrementally risks a double discount or a duplicate free item.

Unknown and malformed effect handling​

CaseBehavior
Unknown actionTypeDo not fail the whole response; log/quarantine
Missing expected detailEffect-level validation failure
Null effectTransactionIdFallback deduplication tuple
Negative discount/pointReject + alert
Item position not foundDo not apply; raise a reconciliation alarm
Duplicate effectDeduplicate
Invalid dateDo not apply the sensitive reward; send to error queue
Unknown code/status enumForward-compatible fallback
Invalid custom payloadQuarantine

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 429 responses

Log fields:

  • Environment/application
  • Correlation ID
  • Masked/hashed integrationId
  • sessionId
  • campaignId
  • ruleId
  • actionType
  • effectTransactionId

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