Skip to main content

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:

ContextResponsibilitySee
ConsumersProfile create/update/read/deleteConsumers, wallets and goals
SessionsCart evaluation, finalization, cancel, refund and detailSessions
EventsBehavioral event triggerEvents
Consumer WalletsRead models for vouchers, coupons, points, point transactions, referrals and tiersConsumers, wallets and goals
GoalsConsumer goal/progress listConsumers, wallets and goals
TransactionsConsumer effect transaction historyConsumers, 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​

QuestionSessionEvent
Does cart/transaction data change?YesNo
Is finalization required?YesNo
Is refund/cancel required?YesNo
Is it a single behavioral action?Usually noYes
Do item position/quantity matter?YesUsually no
Can it trigger goal progress or a reward?YesYes

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 integrationId and a unique sessionId
  • 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
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 effectTransactionId for deduplication.
  • Make integrationId, sessionId, campaignId, ruleId and effectTransactionId structured 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>
CaseHTTPBody
Header missing401 UnauthorizedEmpty body
Invalid API key404 Not FoundCode: 3001, Api Key could not be found!
Rate limit exceeded429 Too Many RequestsLimit 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.

GroupMethodPathSuccess
ConsumersPOST/consumers/upsert200
ConsumersPUT/consumers/upsert/organization ¹204
ConsumersGET/consumers/{integrationId}/profile200
ConsumersPUT/consumers/{integrationId}/session/{sessionId}200
ConsumersDELETE/consumers/{integrationId}204
SessionsPUT/consumers/session/{sessionId}/cancel200
SessionsPUT/consumers/session/{sessionId}/refund200
SessionsGET/consumers/session/{sessionId}/detail/{integrationId}200
WalletsGET/consumerwallets/vouchers200
WalletsGET/consumerwallets/coupons200
WalletsGET/consumerwallets/{integrationId}/points200
WalletsGET/consumerwallets/programtransactions200
WalletsGET/consumerwallets/referrals200
WalletsGET/consumerwallets/{integrationId}/tierprograms ¹200
EventsPOST/events/{integrationId}/trigger200
GoalsGET/goals/active200
TransactionsGET/transactions/search200
ConsumersGET/consumers/getorinsert ¹200
Coupon codesPOST/consumercouponcodes/burn ¹200
CatalogGET/loyaltyprograms/list ¹200
CatalogGET/tierprograms/list ¹200
Pending verification

¹ The following endpoints are not yet verified against the test environment:

  • PUT /consumers/upsert/organization
  • GET /consumerwallets/{integrationId}/tierprograms
  • GET /consumers/getorinsert
  • POST /consumercouponcodes/burn
  • GET /loyaltyprograms/list
  • GET /tierprograms/list
Pending verification

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-Key is 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/Closed sessions; use the separate endpoints for cancel and refund.
  • Business-rule failures can be returned inside HTTP 200 as ruleFailureReasons.
  • Dispatch effects on actionType; deduplicate them on effectTransactionId.
  • Handle money and point fields with decimal/fixed-point data types in application code.
  • Handle unknown enum/effect values in a forward-compatible way.