Core concepts

Perkamo keeps loyalty state isolated by Space. A Space owns its API keys, profiles, event log, program rules, rewards, perks, webhooks and usage meters.

Space

A Space is an isolated environment such as commerce-test or commerce-live. Every API request includes tenant, and that value must match the Space attached to the API key.

Create and review Spaces in the Spaces console.

Field	Meaning
`slug`	Stable Space identifier used in API payloads.
`environment`	`test` or `live`.
`api keys`	Server keys and browser-token metadata scoped to the Space.

Profile

A profile represents one user from your application inside one Space. Choose a stable user_id, preferably your immutable account or customer id.

Good ids:

customer_123
user_9f7c2
account:acme:42

Avoid ids that can change, such as email addresses, unless your product already treats them as permanent identifiers.

Event

An event is an append-only activity fact. Common examples:

user.registered
purchase.completed
booking.completed
lesson.finished
feature.used

Use lowercase namespaced keys. Prefer durable business facts over UI events.

Context

Context carries facts used for rules, debugging and audit trails. Keep it concise and do not include secrets or unnecessary personal data.

json

{
  "order_id": "order_1092",
  "amount": 12900,
  "currency": "CZK",
  "source": "checkout"
}

The SDK rejects reserved state fields in context: xp, wallet, wallets, rewards, level, perks and achievements.

Wallet, level and perks

A wallet is a named point balance such as xp, points or loyalty_points. Levels are derived from a configured wallet. Perks are unlocks returned on the profile; your product decides how to render or fulfill them.

Configure wallet naming in Program wallets and earning behavior in Program rules.

Idempotency

Every event and redemption has a transaction_id. Use the same value when retrying the same business action.

Action	Recommended `transaction_id`
Purchase completed	Order, payment or invoice id
Booking completed	Booking id
Lesson finished	`lesson:{lesson_id}:user:{user_id}`
Reward redeemed	`redeem:{reward_key}:{order_id}`

If a request times out, retry with the same id. Perkamo returns duplicate: true when the action was already processed.

Quickstart

API reference