Introduction

The Loyalty Engine is a multi-tenant loyalty API built for South African commerce. Add points, cashback, stamp cards, and tangible rewards — coupons, gift cards, free items, discount vouchers — to any POS, e-commerce checkout, or mobile app in two API calls.

What you can build

• Event-driven engagement — define your own events (purchase.completed, survey.completed) and reward them with EVENT_TRIGGER programmes (Events)
• Points for every purchase (SPEND_PERCENTAGE or FIXED_POINTS earn rules)
• Redemption — convert points to a rand discount at checkout
• Stamp cards
• Tangible rewards — issue coupons, gift cards, free items, and discount vouchers from any campaign
• Surprise & delight — a reward on every Nth purchase
• Tier-based multipliers (Bronze / Silver / Gold)

How it works

1. Event → Programme → Reward: your app calls POST /events → matching EVENT_TRIGGER programmes fire and rewards are issued
2. Your POS calls POST /transactions/evaluate at checkout → points are awarded and/or rewards are issued
3. Your app calls POST /transactions/redeem when the customer wants to spend points → discount in cents returned
4. All calls are idempotent on their reference (ref / transactionRef) — safe to retry

Base URL

Production:  https://loyalty-engine-production-e5cb.up.railway.app
Test:        Same URL, use sk_test_* keys

Authentication

All requests require an X-API-Key header with a sk_test_* or sk_live_* key. JWT Bearer tokens are supported for portal integrations.

# API Key authentication
curl https://loyalty-engine-production-e5cb.up.railway.app/tenants/YOUR_TENANT_ID/members \
  -H "X-API-Key: sk_test_YOUR_KEY"