Integration overview
This page describes the system boundaries of a Kaizen Loyalty Platform (KLP) integration, the runtime API surface, and the responsibilities of KLP and of your application. Start here, then continue with Authentication and security, Sessions, Events, Consumers, wallets and goals and Effects. Before going live, work through the Production checklist.
System purpose
KLP evaluates transactional or behavioral data from external systems in real time against the active campaign, goal and rule definitions. The result is returned as an effect response that the integrating application applies or shows to the user.
KLP is not a checkout, order-management, payment or inventory system. KLP calculates the applicable campaign result and manages loyalty assets; the client application applies that result in its own channel and owns the commercial transaction lifecycle.
High-level architecture
Client Application / Backend
│
│ X-Api-Key + JSON
▼
KLP Integration Gateway
│
├── Consumer APIs
├── Session APIs
├── Event API
├── Wallet APIs
├── Goal/Tier APIs
└── Transaction Search
│
▼
KLP Rule Engine
│
├── Campaign conditions
├── Consumer/session/event attributes
├── Coupon/referral validation
├── Limits
└── Effects
│
▼
Rule Engine Result
├── effects[]
└── ruleFailureReasons[]
Runtime API surface
The API is organized into the following bounded contexts:
| Context | Responsibility | See |
|---|---|---|
| Consumers | Profile create/update/read/delete | Consumers, wallets and goals |
| Sessions | Cart evaluation, finalization, cancel, refund and detail | Sessions |
| Events | Behavioral event trigger | Events |
| Consumer Wallets | Read models for vouchers, coupons, points, point transactions, referrals and tiers | Consumers, wallets and goals |
| Goals | Consumer goal/progress list | Consumers, wallets and goals |
| Transactions | Consumer effect transaction history | Consumers, wallets and goals |
Integration methods
Backend integration API
The backend integration API is the primary integration method.
Typical scenarios:
- E-commerce backends and checkout services
- CRM/customer-data sync
- Payment and order platforms
- A shared central integration for multiple channels
- Displaying wallet and loyalty history
- Refund/cancel orchestration
Keep the API key as a server-side secret. Every request carries the X-Api-Key header.
Frontend/mobile SDK
The SDK can be used for direct user interaction, loyalty UI and gamification screens. Unlike the API-key model, SDK authentication uses a challenge token and a customer JWT. See Authentication and security.
Run transaction finalization, cancel and refund on the server side through the integration API.
Hybrid model
Recommended model:
- Manage the consumer profile and transaction state with the backend API.
- Evaluate carts with the Session API.
- Send behavioral actions with the Event API or the SDK.
- Show the loyalty/gamification UI with the SDK or your own client UI.
- Call cancel/refund from your backend orchestration.
Domain data models
Consumer
The KLP counterpart of a customer in your system. It is identified by an immutable integrationId.
Session
A stateful shopping or transaction snapshot. It can contain the cart, a coupon, a referral, attributes, additional costs and returned items.
Event
A single user action that does not need a lifecycle. Event route:
POST /events/{integrationId}/trigger
Wallet
The read model of the vouchers, coupons, loyalty points, referral codes and tiers that belong to a consumer.
Goal
Per-consumer progress and completion state within a campaign.
Effect
The result of the rule engine. It is carried with an actionType and an action-specific detail object. See Effects.
Rule failure
A request can succeed at the HTTP level even though a rule was not applied. In that case the API returns 200 and writes the reasons to ruleFailureReasons.
Choosing between a session and an event
| Question | Session | Event |
|---|---|---|
| Does cart/transaction data change? | Yes | No |
| Is finalization required? | Yes | No |
| Is refund/cancel required? | Yes | No |
| Is it a single behavioral action? | Usually no | Yes |
| Do item position/quantity matter? | Yes | Usually no |
| Can it trigger goal progress or a reward? | Yes | Yes |
Session operation model
Session upsert, cancel and refund are separate operations:
PUT /consumers/{integrationId}/session/{sessionId}
├── Open
└── Closed
PUT /consumers/session/{sessionId}/cancel
PUT /consumers/session/{sessionId}/refund
GET /consumers/session/{sessionId}/detail/{integrationId}
The upsert endpoint cannot be called again for a closed session. Use the dedicated endpoints for cancel and refund. See Sessions.
Response content selection
Session and event requests accept an optional ResponseContents list.
Supported enum values:
ConsumerSession
ConsumerProfile
TriggeredCampaigns
RuleFailureReasons
Use this field to leave out response sections your client does not need. Validate the exact response envelope for the values you use with contract tests.
Responsibility boundaries
KLP responsibilities
- Pass consumer/session/event data to the rule engine
- Evaluate campaign conditions and limits
- Produce effects
- Manage wallet, goal and tier state
- Revert supported effects during cancel/refund
- Provide session detail and transaction history
Integrating application responsibilities
- Generate a persistent
integrationIdand a uniquesessionId - Send a current and accurate snapshot
- Keep the API key secure
- Apply effects deterministically and idempotently
- Set up saga/reconciliation between payment/order state and KLP state
- Preserve the cart item position mapping
- Map refund quantity/position information to the original session
- Handle unknown effect/enum values in a forward-compatible way
Recommended backend service split
Checkout / Order Service
├── KLP API Client
│ ├── Consumer Client
│ ├── Session Client
│ ├── Event Client
│ ├── Wallet Client
│ └── Transaction Client
├── Effect Processor
├── Session State Store
├── Idempotency Store
├── Outbox / Saga
└── Observability / Reconciliation
Non-functional requirements
- Rate limit per API key: 300 requests per minute.
- Apply exponential backoff with jitter on
429. - Define an explicit checkout latency budget.
- Track closed, cancel and refund calls with a durable outbox.
- Store
effectTransactionIdfor deduplication. - Make
integrationId,sessionId,campaignId,ruleIdandeffectTransactionIdstructured log fields. - Do not log API keys, JWTs, coupon/voucher/referral codes or PII.
- Keep sandbox and production credentials separate.
Authentication at a glance
Every backend request sends this header:
X-Api-Key: <API_KEY>
| Case | HTTP | Body |
|---|---|---|
| Header missing | 401 Unauthorized | Empty body |
| Invalid API key | 404 Not Found | Code: 3001, Api Key could not be found! |
| Rate limit exceeded | 429 Too Many Requests | Limit of 300 requests per minute |
If write access is not enabled when the API key is created, only GET endpoints can be used. See Authentication and security.
Endpoint catalog
All paths are relative to the integration API base URL, which includes the /api/v1 prefix (for the test environment: https://api-integration.test.kaizenloyalty.com/api/v1). See Environments for the available environments; the production base URL is provided separately. Full request and response schemas are in the API reference.
| Group | Method | Path | Success |
|---|---|---|---|
| Consumers | POST | /consumers/upsert | 200 |
| Consumers | PUT | /consumers/upsert/organization ¹ | 204 |
| Consumers | GET | /consumers/{integrationId}/profile | 200 |
| Consumers | PUT | /consumers/{integrationId}/session/{sessionId} | 200 |
| Consumers | DELETE | /consumers/{integrationId} | 204 |
| Sessions | PUT | /consumers/session/{sessionId}/cancel | 200 |
| Sessions | PUT | /consumers/session/{sessionId}/refund | 200 |
| Sessions | GET | /consumers/session/{sessionId}/detail/{integrationId} | 200 |
| Wallets | GET | /consumerwallets/vouchers | 200 |
| Wallets | GET | /consumerwallets/coupons | 200 |
| Wallets | GET | /consumerwallets/{integrationId}/points | 200 |
| Wallets | GET | /consumerwallets/programtransactions | 200 |
| Wallets | GET | /consumerwallets/referrals | 200 |
| Wallets | GET | /consumerwallets/{integrationId}/tierprograms ¹ | 200 |
| Events | POST | /events/{integrationId}/trigger | 200 |
| Goals | GET | /goals/active | 200 |
| Transactions | GET | /transactions/search | 200 |
| Consumers | GET | /consumers/getorinsert ¹ | 200 |
| Coupon codes | POST | /consumercouponcodes/burn ¹ | 200 |
| Catalog | GET | /loyaltyprograms/list ¹ | 200 |
| Catalog | GET | /tierprograms/list ¹ | 200 |
¹ The following endpoints are not yet verified against the test environment:
PUT /consumers/upsert/organizationGET /consumerwallets/{integrationId}/tierprogramsGET /consumers/getorinsertPOST /consumercouponcodes/burnGET /loyaltyprograms/listGET /tierprograms/list
For the frontend/mobile SDK there are also /me variants of the consumer and wallet endpoints (see Consumers, wallets and goals) and the /events/{integrationId}/trigger-encrypted and /events/me/trigger-encrypted endpoints (see Events). These work with SDK authentication, not with X-Api-Key (see Authentication and security).
Integration principles
X-Api-Keyis required on backend requests.- The API key must have write access for write endpoints.
- To evaluate all campaigns, send
SelectedCampaignIds: []. - Consumer and session identifiers must be immutable and stable.
- The session upsert endpoint cannot be called again on a closed session.
- Use upsert to create and update
Open/Closedsessions; use the separate endpoints for cancel and refund. - Business-rule failures can be returned inside HTTP
200asruleFailureReasons. - Dispatch effects on
actionType; deduplicate them oneffectTransactionId. - Handle money and point fields with decimal/fixed-point data types in application code.
- Handle unknown enum/effect values in a forward-compatible way.