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.

Each Space also has an Event Catalog. An event contract is active, deprecated or discovered, and records whether an Earning rule or Goal refers to it. The catalog powers autocomplete in the console and SDK discovery. An unknown key is accepted so an existing customer integration does not break, but it is classified as unexpected, does not infer customer-state changes, and is shown as a repairable warning in Events and API Activity. Register the key if it is intentional, or fix the sender when it is a typo.

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 goals.

Wallets, levels and Earning rules

A Wallet is a named point balance such as xp, points or loyalty_points. Levels are projections derived from one configured Wallet. An Earning rule matches one trusted event and grants Wallet awards.

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.

Goals

A Goal owns customer progress toward an event-count target. Each Goal has a metric event and target, a window (lifetime, daily, weekly or monthly), optional Wallet awards, and a repeatable policy. A Goal event does not need an Earning rule: point-award cooldowns and caps never suppress Goal progress.

Customer reads return goals.progress and durable goals.completions. Repeatable Goals expose completed cycles plus progress toward the next cycle. Configure them under Goals, or upload a goals config module.

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.

Benefits: Rewards and Perks

A Reward is something a customer deliberately redeems 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 fulfills. Perkamo tracks the balance and idempotency; it does not issue coupons or grant plans on your behalf.

A Perk is a persistent automatic benefit or flag. It can unlock from a Goal completion, Wallet threshold, level, birthday, or an authorized manual action. Perks do not own event-count progress; create a Goal and reference it with a goal_completed unlock condition.

Configure both under Benefits. 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 the customer can only afford that Reward after generating enough value at your target ROI.

You can drive it from either side — fix the ROI and let Perkamo compute Reward costs, or set a Goal target (for example "complete 30 actions") and inspect the economics 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. Reusing the id for a different customer or event returns 409 transaction_id_conflict; use a new id for a different business action.