Quickstart

Perkamo is a server-authoritative loyalty and gamification API. Your backend sends trusted activity events, Perkamo applies the active program rules, and your app reads the resulting profile state.

Use this path for the first integration:

Create a test Space in the Perkamo console.
Create a server API key scoped to that Space.
Store the key in your backend environment.
Emit one event with a stable transaction_id.
Review events, then read the profile state and confirm wallet, level and unlock state.
Move to a live Space only after retries and webhook handling are tested.

Install the SDK

bash

npm install @perkamo/sdk-js

import { createPerkamoClient } from "@perkamo/sdk-js";

const perkamo = createPerkamoClient({
  baseUrl: "https://api.perkamo.com",
  tenant: "commerce-test",
  apiKey: () => process.env.PERKAMO_SECRET_KEY,
  timeoutMs: 5000,
});

Send the first event

Events describe facts from your system. Do not send final points, wallet, level, reward or perk state in event context; Perkamo computes those values from rules.

Configure the earning behavior in Program rules before testing production-like events.

await perkamo.emit(
  "customer_123",
  "purchase.completed",
  {
    order_id: "order_1092",
    amount: 12900,
    currency: "CZK",
  },
  { txId: "order_1092" },
);

The same call with curl:

bash

curl -X POST "https://api.perkamo.com/v1/events" \
  -H "content-type: application/json" \
  -H "x-perkamo-api-key: $PERKAMO_SECRET_KEY" \
  --data '{
    "tenant": "commerce-test",
    "user_id": "customer_123",
    "event": "purchase.completed",
    "transaction_id": "order_1092",
    "context": {
      "order_id": "order_1092",
      "amount": 12900,
      "currency": "CZK"
    }
  }'

Read profile state

const profile = await perkamo.profile("customer_123");
console.log(profile.wallets, profile.level, profile.perks);

bash

curl "https://api.perkamo.com/v1/profile/customer_123" \
  -H "x-perkamo-api-key: $PERKAMO_SECRET_KEY"

Use Customers to inspect the same profile from the console after sending the event.

Production checklist

Use separate test and live Spaces.
Keep sk_test_... and sk_live_... keys from Secret keys in backend secret storage only.
Use natural business ids as transaction_id values for retriable events.
Treat duplicate: true as a successful idempotent replay.
Retry network failures and 5xx with the same transaction id.
Do not automatically retry validation, authentication or authorization errors.

Core concepts