Sessions
| Operation | Method | Path | Success |
|---|---|---|---|
| Upsert session | PUT | /consumers/{integrationId}/session/{sessionId} | 200 |
| Cancel session | PUT | /consumers/session/{sessionId}/cancel | 200 |
| Refund session | PUT | /consumers/session/{sessionId}/refund | 200 |
| Session detail | GET | /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
| Field | Rule |
|---|---|
integrationId | The consumer's immutable external identifier |
sessionId | A 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
| Field | Type | Required | Description |
|---|---|---|---|
Session.SelectedCampaignIds | string[]? | No | Campaign IDs to evaluate |
Session.StateType | enum | Yes | Session state |
Session.Attributes | Dictionary<string, object>? | No | Session-level custom attributes |
Session.AdditionalCosts | Dictionary<string, object>? | No | Session-level additional cost data |
Session.Coupon | object | No | Coupon request |
Session.Coupon.Code | string | If a coupon is sent | Coupon code |
Session.Referral | object | No | Referral request |
Session.Referral.Code | string | If a referral is sent | Referral code |
Session.CartItems | array | No | Snapshot of the cart items |
Session.ReturnedCartItems | array | No | Snapshot of the returned items |
ResponseContents | enum array | No | Sections to include in the response |
Cart item model
| Field | Type | Description |
|---|---|---|
Name | string? | Product name |
Sku | string | Persistent product identifier |
Quantity | int | Quantity |
Price | float? | Unit price |
Category | string? | Category |
Position | int? | Stable position within the transaction |
Attributes | Dictionary<string, object>? | Item attributes |
AdditionalCosts | Dictionary<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
OpenandClosed. - Cancellation uses the dedicated
/cancelendpoint. - Refunds use the dedicated
/refundendpoint. - Treat
Cancelled,RefundandPartiallyRefundas 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
Openagain with the samesessionId.
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
}
]
}
| Field | Type | Description |
|---|---|---|
ReturnItems | array | Original cart items to refund |
ReturnItems[i].Quantity | int | Quantity to refund |
ReturnItems[i].Position | int | Original 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
| Field | Type | Description |
|---|---|---|
stateType | session state enum | Latest state |
requestData | ConsumerSessionRequestModel | Session snapshot |
resultData | RuleEngineResultModel | Latest rule result |
createdDate | DateTime | Creation timestamp |
lastUpdatedDate | DateTime | Latest 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
| Case | HTTP | Body |
|---|---|---|
| API key header missing | 401 | Empty body |
| API key invalid | 404 | Code: 3001 |
See Authentication and security for details.
Client processing rules
- Treat the latest
Openresponse as the result for the current cart snapshot. - Remove earlier provisional KLP adjustments before applying the latest effect set.
- Store
effectTransactionIdas the deduplication key. - Preserve the
positionmapping for item-level effects. - An unknown
actionTypemust not make deserialization of the whole response fail. - Handle
ruleFailureReasonsas 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
Closedrequest 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 payload400or invalid key404/3001. - You can retry
429and transient5xxresponses with exponential backoff and jitter.
Test checklist
- Open session create
- Multiple
Openupdates with the same session ID -
Closedwithout a priorOpen - Repeated upsert call on a closed session
- Empty
SelectedCampaignIds - Specific campaign filter
- Coupon and referral request
- Session and item
AdditionalCosts - Cart item
Positionmapping -
ResponseContentsvariations - Rule failure inside HTTP 200
- Cancel a valid session
- Cancel an invalid session / Conflict 2014
- Cancel request
ReturnItemssemantics - Partial refund
- Full refund
- Already fully returned item
-
returned: trueitem-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