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

Use this path for the first integration:

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

Install the SDK

npm install @perkamo/sdk

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

const perkamo = createPerkamoClient({
  apiKey: () => process.env.PERKAMO_SECRET_KEY,
});

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.

Use your application's stable user id as the Perkamo customer id. If you need customer metadata such as e-mail, name or a CRM id, identify the customer from backend code:

await perkamo.identify("customer_123", {
  email: "customer@example.test",
  name: "Customer Test",
  crm_id: "crm_123",
});

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

Read customer state

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

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

Use the API reference only when you need raw HTTP requests instead of an official SDK.

Use Perkamo from an AI agent

Connect hosted MCP or the @perkamo/mcp npm adapter when an AI agent should inspect customers, review program configuration or prepare supervised changes. Hosted OAuth is the managed multi-Space option. The npm adapter is available for MCP clients that launch a local stdio command.

Production checklist

• Use separate test and live Spaces.
• Keep sk_test_... and sk_live_... keys from Server 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.