Every point, accounted for.

Immutable, append-only ledger as source of truth

• Every point movement is a permanent entry — earn, redeem, expiry, reversal, transfer
• No row is ever updated or deleted; corrections are written as new compensating entries
• Reconstruct any customer's balance, at any point in time, directly from the ledger

Strict transactional consistency

• Every balance change commits atomically with the transaction, ledger, event, and audit log
• No half-written transactions, no orphaned ledger lines, no balance drift

Nightly reconciliation

• Random-card sampling sums the ledger by bucket and compares to cached balances
• Drift is detected, logged, and surfaced — not silently absorbed

FIFO point consumption

• Oldest earn batches are redeemed first — clean tax and accounting treatment
• Every redeemed point traces back to the specific earn batch it came from

Defensive integrity at the database level

• Balances cannot go negative — enforced by the database, not just the app
• Reversal of an earn that has already been spent is blocked, not silently allowed

Database-per-tenant architecture

• Each tenant has a dedicated PostgreSQL database — no shared rows, no cross-tenant queries
• The hardest possible isolation boundary in a multi-tenant SaaS

JWT authentication at the gateway

• API gateway handles JWT validation, rate limiting, and IP allow-listing before requests reach the engine

Idempotency-Key on every write

• Retry-safe API — duplicate POS submissions never produce duplicate points
• Two layers of dedup: explicit key plus a bill / order reference fallback

Secure card number generation

• Cryptographically random, Luhn-checksummed, program-prefixed card numbers
• Typo'd cards bounce before any DB write

Built for compliance frameworks

• SOC 2 / ISO / GDPR / KSA data-residency considerations baked into the architecture
• Append-only tables, immutable audit trail, request tracing — the controls auditors look for

REST API for every operation

• Earn, redeem, reverse, refund, balance inquiry, customer management, transaction lookup
• One contract used by POS, e-commerce, mobile apps, kiosks, call center, and admin tools

Five ways to identify a customer at the counter

• Card ID, card number, mobile, email, external CRM ID — pick whichever your channel has
• All five resolve to the same wallet behind the scenes

Omnichannel by design

• Same customer, same balance, across every store, your website, your mobile app, and any future channel
• Channel attribution recorded on every transaction (store / ecom / app / kiosk / call_center)

No imposed UI

• You design the customer experience — the platform exposes the data and operations cleanly
• Branded loyalty pages, mobile wallets, custom dashboards all sit on top of the same API

Line-level earn for multi-product bills

• Send a bill with multiple lines; each line earns, holds, or skips independently based on category rules
• Service fees skip cleanly; subscriptions hold until activation; consultations earn immediately — all in one call

Per-category earning rules

• Each category decides: earn or skip, earn now or hold, earn on discounted items or not
• Priority-driven resolution when a product matches multiple categories

Hold-and-release for subscriptions and pre-paid plans

• Points held when a customer pre-pays for a 30-day plan
• Released day-by-day (or however your business wants) as the service is delivered

POS-friendly refund flow

• One endpoint handles the entire refund — POS doesn't need to know if points are in hold or available
• Held points cancelled; available points reversed; mixed cases handled automatically
• Partial refunds, line-item refunds, full refunds — all supported

Configurable expiry and reversal windows per program

• Points expire per-program (e.g. 12 months from earning)
• Different windows for earn vs. redeem reversals (e.g. 90 days vs. 1 day)

Backdated transaction support

• Migrate opening balances and historical activity from legacy systems with the correct effective dates

Transactional event outbox

• Every point movement, tier change, card issuance, and reversal publishes a clean event
• At-least-once delivery, with consumer-side deduplication on a stable event ID

Redis Streams for downstream consumers

• Notification services (SMS, email, push) consume the same stream
• CRM sync, BI pipeline, fraud detection, marketing automation — all see the same canonical event

No silent failures

• Events that fail to publish are retried, then escalated to a visible dead-letter state
• "Event published but database rolled back" cannot happen — the outbox makes the two atomic

Nightly tier evaluation

• Walks every active card against its tier rules; upgrades and downgrades applied automatically
• Dry-run mode lets operators preview impact before a real run

Point expiry job

• Identifies points past their expiry date with unconsumed balance
• Writes expiry transactions with full ledger trail

Reconciliation job

• Samples random cards each night; flags any drift between cached balances and the ledger

Expiring-points report

• List every customer with points expiring before a chosen date
• Feed into your notification workflows ("you have 250 points expiring in 30 days")

All jobs are externally triggered

• Run from any scheduler — system cron, Kubernetes CronJob, Airflow — the loyalty service stays stateless