canonical: https://jentic.com/apis/koomalooma.com/koomalooma

# koomalooma Partner API

The koomalooma Partner API lets merchants enrol customers in koomalooma's loyalty Business Process as a Service and award them points for in-app or in-store actions. The API exposes two operations - registering a user and assigning point commitments tied to a defined campaign - while koomalooma handles signup confirmation, points accounting, and reward fulfilment in over 80 countries. Authentication is by API key passed in a header. The service is intended for mobile and web stores running referral, purchase, or engagement-based loyalty programmes.

## For AI agents

Register customers in a koomalooma loyalty programme and award them points for purchases, referrals, or other actions through a partner-issued API key.

## Scope

Does not handle reward redemption, balance queries, or campaign configuration - use for user enrolment and points assignment only.

## Capabilities

- Register a new end-user in a koomalooma loyalty programme tied to the partner account
- Assign points to a registered user for a specific campaign action such as a purchase or referral
- Reference campaign identifiers configured in the koomalooma backend when issuing point commitments
- Pass external user identifiers from the partner system so points map back to the merchant's customer record
- Use a single header-based API key per partner to authorise both user creation and points assignment

## Use cases

### Purchase reward issuance

When a customer completes a checkout in a merchant's online store, the merchant calls the koomalooma Partner API to assign campaign points tied to the purchase. koomalooma handles points balance accounting, tier progression, and reward delivery in 80+ countries, removing the need for the merchant to build a loyalty backend. Implementation is typically a one-day effort once campaign IDs are configured in the koomalooma dashboard.

Example prompt: Call POST `/users/{user_id}/commitments` with the user's koomalooma user_id and the purchase campaign ID to credit the configured point amount.

### Referral programme onboarding

A referral landing page collects a new customer's details, registers them in koomalooma via POST /users, and immediately awards referral points to both the new and referring users via separate commitment calls. koomalooma manages the referral chain, country eligibility, and fraud checks. The pattern is widely used by mobile app and DTC ecommerce teams to launch referral programmes without standing up a loyalty service.

Example prompt: Register a new user with POST /users using the referral landing form data, then call POST `/users/{user_id}/commitments` with the referral campaign ID.

### In-app engagement rewards

A mobile app awards points for non-purchase actions - completing a profile, posting a review, sharing on social - by mapping each action to a koomalooma campaign and calling the commitments endpoint when the action fires. koomalooma tracks the user's running balance and triggers reward delivery when thresholds are met.

Example prompt: When a user completes their profile, call POST `/users/{user_id}/commitments` with the 'profile-complete' campaign ID to credit 50 points.

### Agent-managed loyalty actions via Jentic

An AI agent handling post-purchase customer workflows searches Jentic for 'award loyalty points' and is matched to the koomalooma commitments operation. The agent reads order data from the merchant system, calls Jentic to execute the points commitment with the correct campaign ID, and confirms the response - without holding the koomalooma API key in its context.

Example prompt: Use Jentic to load koomalooma_assign_points, then execute it with user_id 'u_12345' and campaign 'purchase-tier-1' for a verified order.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/users` | Create a user in the partner programme |
| POST | `/users/{user_id}/commitments` | Assign campaign points to a user |

## Key resources

- **Users** — Register a new user in the partner's koomalooma loyalty programme
- **Commitments** — Assign points to a registered user against a configured campaign

## Why Jentic

- **Setup:** Wiring the koomalooma Partner API by hand means passing the JWT your koomalooma contact issued in the X-KoomaLooma-JWT header on every call to api.koomalooma.com. Through Jentic you install once, import the koomalooma Partner API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** koomalooma puts the user id in the URL path (`/users/{user_id}/commitments`), so a rule can pin your agent to one user: it can enrol that user and assign points and nothing else. You choose the operations it may call, so anything beyond enrolment and points assignment is not included unless you add it.
- **Credential handling:** Your koomalooma partner token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'award loyalty points' or 'enrol a member', and Jentic returns the matching koomalooma operation with its input schema so the correct user_id and campaign are surfaced without browsing the reference docs.

## Related APIs

- **LoyaltyLion** — Loyalty platform with broader Shopify-focused points and rewards APIs
- **Loyalzoo** — Digital loyalty stamp and points platform aimed at SMB retailers
- **Smile.io** — Loyalty and rewards platform with points, referrals, and VIP tiers
- **Shopify** — Source of order events that trigger koomalooma point commitments

## FAQ

### What authentication does the koomalooma Partner API use?

The API uses an API key passed in the request header. Jentic stores this key encrypted in your Jentic One instance and injects it per call so the agent never sees the raw secret.

### Can I create users and award points in a single call with the koomalooma Partner API?

No. User creation is POST /users and points assignment is a separate POST `/users/{user_id}/commitments.` A typical flow chains the two in sequence using the user_id returned by the first call.

### What are the rate limits for the koomalooma Partner API?

Rate limits are not declared in the spec. koomalooma applies per-partner ceilings - contact support@koomalooma.com for the limit on your account and design retries with exponential backoff.

### How do I award referral points through Jentic?

Search Jentic for 'award loyalty points', load the POST `/users/{user_id}/commitments` operation, and execute it with the referral campaign ID configured in your koomalooma backend. Install the SDK with pip install jentic to call it from Python.

### Does the koomalooma Partner API let me read a user's points balance?

No read endpoint is exposed in this spec. The Partner API covers user creation and points commitments only - balance lookups and reward redemption are handled inside the koomalooma platform.

### Can I limit what my agent is allowed to do with the koomalooma Partner API?

Yes. Because you self-host Jentic One, your own rules decide which koomalooma operations and credentials the agent may use, so you can allow only user enrolment (POST /users) and points assignment (POST `/users/{user_id}/commitments`) and nothing more. Since the user id sits in the URL path, a rule can pin the agent to a single user, letting it enrol that user and credit campaign points while blocking any other call. Your koomalooma partner token is held by your Jentic One instance and injected at execution time, so the agent never sees the raw secret.