Program
Rules, currency, tiers, rewards, market, and lifecycle for one loyalty proposition.
Understand where loyalty value lives.
Learn the small set of objects and invariants that keep points explainable, reversible, and financially governable.
Developer docs · no accountSandbox firstContract version 1.2.0
Five nouns explain the platform.
Member
Your external customer identity plus consent, status, program profile, and qualification state.
Event
A business fact such as a purchase, return, visit, referral, or registered custom behavior.
Reward
A governed benefit with eligibility, cost, inventory, and fulfillment behavior.
Ledger
The balanced, append-only record from which point balances and liability evidence are derived.
A displayed balance is an outcome, not the source.
Loyumi records balanced movements and derives the member state from them. That makes an award explainable and a return reversible.
Pending→Available→Reserved→Redeemed·Expired
- Pending
- Earned but not yet spendable, commonly during a return window.
- Available
- Spendable value after applicable hold rules pass.
- Reserved
- Temporarily held for an in-progress redemption.
- Redeemed
- Consumed by a completed fulfillment.
- Expired
- Removed by an explicit expiration policy and recorded for audit.
One business fact gets one stable key.
A network timeout does not tell you whether the server committed. Reuse the same idempotency key and identical body so a retry can recover the first outcome.
- Use a durable commerce reference, not a random value per attempt.
- Keep the key stable across workers and queues.
- Never reuse a key for a different business fact.
Key mapping
purchase order-10042 → order-10042
return return-10042-1 → return-10042-1
choice anniversary-42 → anniversary-42Sandbox and production are separate worlds.
Sandbox
- Test-shaped customers and orders
- Independent program configuration
- Sandbox-only keys and environment ID
- No production customer impact
Production
- Separate credentials
- Readiness controls before activation
- Real liability and customer outcomes
- Monitoring, finance, risk, and support owners
Conversion is possible only with an explicit contract.
Two merchants may agree to convert value, but that is not the same as creating an uncontrolled cross-merchant currency.
Bilateral agreement
Name the issuer, redeemer, funded value, and termination rules.
Conversion policy
Set the ratio, rounding, minimum, maximum, markets, and eligible members.
Settlement
Record who owes whom, when funds move, and how disputes reconcile.
Risk controls
Apply velocity limits, fraud monitoring, sanctions obligations, and reversals.
Customer clarity
Show the exact value before confirmation and preserve consent evidence.