Core concepts

Perkamo is organized around Spaces. A Space is where one loyalty or gamification program is configured, tested and operated.

Space

A Space is the customer-facing boundary for one program environment, such as a test integration or a live production program. It keeps configuration, credentials, customers, events, webhooks and usage data separate from other Spaces.

Use a test Space while building and validating rules. Use a live Space only for production traffic. Server API keys and signing keys are scoped to one Space, so SDK requests do not need a separate Space field. Client tokens derive their Space from the KID in the token header.

Create and review Spaces in the Spaces console.

Customer

A customer 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.

{
  "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 customer; your product decides how to render or fulfill them.

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

Earning rules can award a fixed wallet amount or a formula derived from event context. For ecommerce purchases, a rule can award points with a formula such as {{product_price}} * 10. Formula awards support numbers, {{context.path}} references and arithmetic operators only; Perkamo rounds the result down to whole non-negative points before applying caps or boosts.

Achievements

An achievement is a goal that counts one event toward a target and grants wallet points when reached. Each achievement names a metric event and target count, a window (lifetime, daily, weekly or monthly), a badge and whether it is repeatable. Progress and unlocks are returned on the customer under achievements (completed, in_progress, unlocked), so your UI can render badges and progress bars.

Configure achievements in Program rules, or upload an achievements config module via the API.

Boosts

A boost multiplies the points earned from events for a window of time or for a segment of customers. A boost has a multiplier, an optional appliesTo wallet list, an optional active window (start/end or a recurring schedule) and a source that decides who it applies to (everyone, an event-context match, a customer-trait match, or a schedule). Boosts are applied after formula rounding, and active boosts are returned on the customer under active_boosts.

Configure boosts under Program rules, or upload a boosts config module.

Rewards

A reward is something a customer can redeem by spending wallet points. Redemption subtracts the wallet cost and returns a declarative effect discriminated by type — coupon, free_shipping, gift_card, entitlement or custom — which your backend fulfils. Perkamo tracks the balance and idempotency; it does not ship coupons or grant plans on your behalf. See POST /v1/rewards/redeem for the request and effect shapes.

ROI economy

Instead of hand-tuning point numbers, you can describe your program economically and let Perkamo keep it profitable. Set a target ROI and currency, give each valuable action a business value (what it is worth to you) and each reward a cost (what granting it costs you). Perkamo back-solves the point mechanics: how many points each action earns and how many a reward costs, so a reward only unlocks once it has paid for itself at your target ROI.

You can drive it from either side — fix the ROI and let Perkamo compute the unlock threshold, or pin a milestone (for example "complete 30 actions") and see the ROI it implies. The console shows a live ROI readout and a short setup wizard. Configure it under Program rules.

Idempotency

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

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