Skip to main content

Sessions

OperationMethodPathSuccess
Upsert sessionPUT/consumers/{integrationId}/session/{sessionId}200
Cancel sessionPUT/consumers/session/{sessionId}/cancel200
Refund sessionPUT/consumers/session/{sessionId}/refund200
Session detailGET/consumers/session/{sessionId}/detail/{integrationId}200

Test base URL (see Environments):

https://api-integration.test.kaizenloyalty.com/api/v1

Every request authenticates with your API key (see Authentication and security):

X-Api-Key: <API_KEY>

When to use sessions​

Use a session when cart or transaction data changes over time, when rule engine evaluation depends on a snapshot of the transaction, and when the transaction must be finalized, cancelled or refunded.

Examples:

  • Adding items to or removing items from the cart
  • Changing quantity, price or additional costs
  • Applying a coupon or referral code
  • Evaluating campaigns before checkout
  • Finalizing a purchase
  • Cancelling after a payment failure
  • Refunding all items or some of them
  • Querying the latest session state

For single consumer actions that do not need a shopping lifecycle, use Events instead.

Identifiers​

FieldRule
integrationIdThe consumer's immutable external identifier
sessionIdA unique, stable identifier for a single transaction journey

Every session ID must be unique. Use the same sessionId for every update to the same open session. You cannot call the upsert endpoint again for a closed session.

Upsert session​

Endpoint​

PUT /consumers/{integrationId}/session/{sessionId}

Request​

{
"Session": {
"SelectedCampaignIds": [],
"StateType": "Open",
"Attributes": {
"ShippingCity": "Antalya"
},
"AdditionalCosts": {
"Shipping": 50.00
},
"Coupon": {
"Code": "SAMPLECODE"
},
"Referral": {
"Code": "REFERRALCODE"
},
"CartItems": [
{
"Name": "Nike Air Jordan",
"Sku": "NKAJ20240709",
"Quantity": 1,
"Price": 40.00,
"Category": "Shoes",
"Position": 0,
"Attributes": {
"Brand": "Nike"
},
"AdditionalCosts": {
"Packaging": 5.00
}
}
],
"ReturnedCartItems": []
},
"ResponseContents": [
"TriggeredCampaigns",
"RuleFailureReasons"
]
}

AdditionalCosts, Position, ReturnedCartItems and ResponseContents are part of the official request model, even when a given request does not use all of them.

Session request model​

FieldTypeRequiredDescription
Session.SelectedCampaignIdsstring[]?NoCampaign IDs to evaluate
Session.StateTypeenumYesSession state
Session.AttributesDictionary<string, object>?NoSession-level custom attributes
Session.AdditionalCostsDictionary<string, object>?NoSession-level additional cost data
Session.CouponobjectNoCoupon request
Session.Coupon.CodestringIf a coupon is sentCoupon code
Session.ReferralobjectNoReferral request
Session.Referral.CodestringIf a referral is sentReferral code
Session.CartItemsarrayNoSnapshot of the cart items
Session.ReturnedCartItemsarrayNoSnapshot of the returned items
ResponseContentsenum arrayNoSections to include in the response

Cart item model​

FieldTypeDescription
Namestring?Product name
SkustringPersistent product identifier
QuantityintQuantity
Pricefloat?Unit price
Categorystring?Category
Positionint?Stable position within the transaction
AttributesDictionary<string, object>?Item attributes
AdditionalCostsDictionary<string, object>?Item-level additional costs

ReturnedCartItems uses the same cart item model.

In your application code, handle Price, discounts and other monetary values as decimal or fixed-point numbers, even though the model types them as float/double.

ResponseContents enum​

ConsumerSession
ConsumerProfile
TriggeredCampaigns
RuleFailureReasons

Use this field to limit the response payload to the sections you need. Verify the default response behavior when ResponseContents is omitted with a runtime contract test.

SelectedCampaignIds​

To evaluate all eligible campaigns:

"SelectedCampaignIds": []

To evaluate specific campaigns:

"SelectedCampaignIds": [
"4JC9YlDLJV30ysAKMbAc5w=="
]

Sending null is a legacy form; new client implementations must send an empty list.

Session state enum​

Open
Closed
Cancelled
Expired
Refund
PartiallyRefund

Each operation uses its own mechanism:

  • Session upserts use Open and Closed.
  • Cancellation uses the dedicated /cancel endpoint.
  • Refunds use the dedicated /refund endpoint.
  • Treat Cancelled, Refund and PartiallyRefund as result or detail states of a session. Do not send them directly in an upsert request.

Upsert lifecycle​

Open​

  • Starts a new session or updates an existing open session.
  • Every request must carry the current snapshot.
  • Effects in the response can be provisional.
  • When the cart changes, send Open again with the same sessionId.

Closed​

  • Finalizes the transaction in KLP.
  • Campaign limit, code and loyalty results can be finalized.
  • You cannot call the upsert endpoint again for a closed session.
  • If you need to cancel or refund after closing, use the dedicated endpoints.
Open ──updates──> Open ──finalize──> Closed
├── cancel
└── refund / partially refund

Upsert response​

Success and business failure can both return HTTP 200. The response is the rule engine result model; see Effects for effect types and rule failure reasons.

Effect success​

{
"effects": [
{
"campaignId": "g8JYWnwRK6-VB8Ti9LvS1w==",
"rulesetId": "RQC1pkGN7ooGh4AwO9bdXA==",
"ruleId": "b605580f-1c3a-4152-97e4-4fdac8c0bb86",
"ruleName": "Campaign rule",
"ruleIndex": 2,
"id": "ae9b207d-af31-4b1f-8686-5e5e6b975520",
"name": "Referral reward",
"actionType": "GiveReferralCode",
"detail": {
"effectTransactionId": "18af1088-311d-4a95-92aa-eb19b454049e",
"referralCode": {
"poolId": "6908555e5308cd2540202ae3",
"id": "6908555e5308cd2540202ae3-690855697f49535f8e8070d1",
"code": "UD8JLYPL",
"type": "Award"
}
}
}
],
"ruleFailureReasons": []
}

Business-rule failure​

{
"effects": [],
"ruleFailureReasons": [
{
"campaignId": "...",
"rulesetId": "...",
"details": [
{
"ruleId": "...",
"ruleName": "...",
"ruleIndex": 2,
"couponId": null,
"referralId": null,
"type": "Limit",
"index": 0,
"message": "..."
}
]
}
]
}

HTTP 200 alone does not mean a campaign was applied. Always evaluate effects and ruleFailureReasons together.

Cancel session​

Endpoint​

PUT /consumers/session/{sessionId}/cancel

Example request​

{
"ReturnItems": [
{
"Quantity": 1,
"Position": 1
}
]
}

Cancelling a session automatically reverts the reversible effects applied during the session.

Reversible effects:

RedeemCouponCode
GiveCouponCode
GiveVoucherCode
GiveLoyaltyProgramPoints
RedeemLoyaltyProgramPoints
IncreaseGoalProgress

A cancel response can also include SetDiscountPerItem, so do not treat this list as exhaustive. Test the actual reversible-effect behavior for your campaigns.

Success​

Returns 200 with the reverted effects.

Invalid cancel​

A business conflict can still return 200:

{
"effects": [],
"ruleFailureReasons": [
{
"campaignId": null,
"rulesetId": "iStQE2vR0TLN96thVKALGQ==",
"details": [
{
"ruleId": null,
"ruleName": null,
"ruleIndex": null,
"couponId": null,
"referralId": null,
"type": "Session",
"index": 0,
"message": "Conflict-Code:2014, Message:Session is not valid for cancel"
}
]
}
]
}

The partial-cancel semantics of the ReturnItems field in a cancel request are not defined. Verify them with a contract test before going to production.

Refund session​

Endpoint​

PUT /consumers/session/{sessionId}/refund

Request​

{
"ReturnItems": [
{
"Quantity": 1,
"Position": 1
}
]
}
FieldTypeDescription
ReturnItemsarrayOriginal cart items to refund
ReturnItems[i].QuantityintQuantity to refund
ReturnItems[i].PositionintOriginal session/cart position

Refundable effects:

SetDiscountPerItem
CustomEffectPerItem

Both partial and full refunds are supported. A returned item part in the response looks like this:

{
"value": 10,
"subPosition": 0,
"returned": true
}

If an item has already been fully returned, the API can return ruleFailureReasons inside a 200 response:

Conflict-Code:1, Message:Item(s) already fully returned. Position(s): 1

Session detail​

Endpoint​

GET /consumers/session/{sessionId}/detail/{integrationId}

Response model​

FieldTypeDescription
stateTypesession state enumLatest state
requestDataConsumerSessionRequestModelSession snapshot
resultDataRuleEngineResultModelLatest rule result
createdDateDateTimeCreation timestamp
lastUpdatedDateDateTimeLatest update timestamp

Session detail can show the server-assigned position values for the cart items in the request, as well as the additionalCosts and returnedCartItems state. Use this endpoint to confirm the original position mapping before a refund.

If the session is not found:

404 Not Found
{
"Code": 2002,
"Message": "Code:2002, Message:Session could not be found!"
}

Authentication errors​

CaseHTTPBody
API key header missing401Empty body
API key invalid404Code: 3001

See Authentication and security for details.

Client processing rules​

  • Treat the latest Open response as the result for the current cart snapshot.
  • Remove earlier provisional KLP adjustments before applying the latest effect set.
  • Store effectTransactionId as the deduplication key.
  • Preserve the position mapping for item-level effects.
  • An unknown actionType must not make deserialization of the whole response fail.
  • Handle ruleFailureReasons as a business outcome.
  • Track closed, cancel and refund calls with a durable outbox or saga.
  • Use session detail for reconciliation and support.

Retry and idempotency​

  • After a network timeout, you can retry the upsert with the same sessionId; deduplicate effects when applying them locally.
  • If the server processed a Closed request but the client did not receive the response, use session detail to check the result.
  • Repeated cancel or refund calls can return a business conflict inside 200; do not treat a call as successful based on the HTTP status alone.
  • Do not automatically retry 401, invalid payload 400 or invalid key 404/3001.
  • You can retry 429 and transient 5xx responses with exponential backoff and jitter.

Test checklist​

  • Open session create
  • Multiple Open updates with the same session ID
  • Closed without a prior Open
  • Repeated upsert call on a closed session
  • Empty SelectedCampaignIds
  • Specific campaign filter
  • Coupon and referral request
  • Session and item AdditionalCosts
  • Cart item Position mapping
  • ResponseContents variations
  • Rule failure inside HTTP 200
  • Cancel a valid session
  • Cancel an invalid session / Conflict 2014
  • Cancel request ReturnItems semantics
  • Partial refund
  • Full refund
  • Already fully returned item
  • returned: true item-part mapping
  • Session detail after Open
  • Session detail after Closed
  • Session detail after partial refund
  • Session not found / Code 2002
  • Invalid API key / Code 3001
  • Missing API key / 401
  • Duplicate effect deduplication
  • Unknown action type