Core Concepts
Understanding these concepts helps you design a reliable Otonum integration and a clear loyalty experience for members.
For endpoint contracts, payload schemas, and operation examples, use the API Reference.
Member Identity
A member is identified by a personal code generated at enrollment.
Personal Code
A personal code is a short identifier (for example JANE2026) that the member presents at checkout. Your integration uses this code for reward-related operations.
Enrollment Modes
| Mode | Typical use case |
|---|---|
| Single | Real-time enrollment during registration or in-store opt-in |
| Bulk | Batch migration of an existing member base |
Enrollment usually includes email, first name, last name, and preferred language.
Member Balance Fields
| Field | Meaning |
|---|---|
balance | Currently available for redemption |
totalEarned | Cumulative rewards earned since enrollment |
totalRedeemed | Cumulative rewards redeemed |
totalReserved | Amount reserved in active vouchers |
totalReserved is temporarily unavailable until the voucher is consumed or expires.
Loyalty Programs
Otonum supports points, cashback, or both depending on tenant configuration.
Points
Points are accumulated from eligible purchases and later converted to redeemable value.
Cashback
Cashback credits a portion of eligible spend directly to the member wallet.
Vouchers
A voucher is a single-use discount instrument created from member balance.
Voucher Lifecycle
- Member accumulates points or cashback
- Member requests redemption
- Otonum creates voucher and reserves value
- Voucher is consumed at purchase or expires after 30 days
- Expired voucher value returns to available balance
In 🧪 Sandbox, voucher creation and validation are restricted by design for certain operations. Use mocks in automated tests where needed.
Purchases and Reward Processing
A purchase submission triggers campaign evaluation and reward calculation.
Core data points include member identity, paid amount, total amount, and optional redemption references.
Processing is asynchronous. Purchase submission returns a taskId, then Otonum completes reward processing in the background.
See Task Status for completion tracking guidance.
Transaction History
Otonum maintains a paginated loyalty event history per member for support, reconciliation, and member-facing history views.
Campaigns
Campaigns define trigger conditions and reward logic. They are configured in the Rewards App and evaluated automatically when relevant purchase events are submitted.
Data Format
All API exchanges use JSON.
See Request Format for date and amount conventions.