PLAIN LANGUAGE · ACCOUNT-FREE GUIDE

Make loyalty feel simple before you make it powerful.

Loyumi helps merchant teams design, operate, and govern customer rewards without hiding the economics. Start with one clear promise, prove it in Sandbox, and earn the right to launch.

Build my 55-minute plan Developer documentation

What “under an hour” means

When your inputs and console access are ready, you can finish a review-ready Sandbox plan in about 55 minutes. Production stays locked until identity, commerce, migration, reconciliation, security, and approval evidence passes.

01 · ORIENT

One platform, five jobs.

Loyumi is the operating layer between a merchant’s customer promise and the systems that must honor it.

Design

Shape programs, tiers, rewards, campaigns, limits, pending rules, and expiration.

Prove

Use an isolated Sandbox to test earning, retries, balances, returns, and customer explanations.

Operate

Trace customer value to business evidence and recover without rewriting history.

Govern

Keep production behind evidence, ownership, least privilege, reconciliation, and approval.

Learn

Measure participation, customer value, margin, and outstanding obligations with defined metrics.

WHO THIS IS FOR

A shared language for the whole merchant team.

Program ownersPromise, rules, and customer experience
Growth teamsPatterns, campaigns, and learning
Finance & riskCost, liability, limits, and evidence
OperationsSupport, incidents, and recovery
Technical ownersIdentity, commerce, API, and observability

02 · KNOW THE BOUNDARY

Use what exists. Label what is still a preview.

No invented customers, transactions, results, connectors, or adoption claims are used in this guide.

Available

Guided merchant console

Configure organizations, environments, programs, members, rewards, campaigns, controls, and readiness evidence.

Available

Server-side HTTP API

Use the published API for supported earning, returns, member reads, registered events, offers, and choice benefits.

Available

Traceable loyalty ledger

Keep earning, redemption, pending value, returns, adjustments, and expiry connected to evidence.

Requires your integration

Commerce and identity

Your trusted systems must identify the customer and send real business facts. This guide does not promise a connector catalog.

Local preview

Widget Studio

Compose and validate device-local design drafts. A hosted production widget runtime is not represented as available.

Governed design

Partner point conversion

Design bilateral exchange with ratios, settlement, limits, reversals, and customer clarity. No public conversion API is claimed.

Package boundary: No official JavaScript, iOS, or Android SDK is represented as published. Use the documented HTTP API from trusted server infrastructure.

Customer-surface boundary: Loyumi does not currently claim a hosted production customer wallet or embed runtime. Your team owns the live web or mobile experience, calls its trusted backend, and keeps Loyumi credentials off customer devices.

03 · START SMALL

Your 55-minute Sandbox plan.

When your program inputs and console access are ready, each check earns visible progress on this device. It is encouragement—not production evidence, certification, or cloud-synced state.

YOUR DEVICE-LOCAL PROGRESS0 of 55 guided minutes checked

Check a step only after its evidence sentence is true.

5 MINChoose one customer outcome
Pick one behavior to improve first: a second purchase, a useful profile, a referral, or recognition of your best customers.
Done when: Write one sentence: “We want members to ___ because ___.”
5 MINPick a simple program pattern
Start with one pattern below. More mechanics can come after customers understand the first promise.
Done when: Name the pattern and the customer moment it improves.
10 MINSet the value and the guardrails
Choose an earn rule, a first meaningful reward, pending and expiration rules, and a clear cost limit.
Done when: Explain how a typical engaged member reaches the first reward and what bounds the cost.
10 MINWrite the customer promise
Use plain words for earning, balance states, reward availability, returns, and expiration. Avoid making customers decode point math.
Done when: A new team member can explain the program correctly in under one minute.
10 MINConfigure the Sandbox version
Create the program in the merchant console, keep it in Sandbox, and enter only values you are prepared to review.
Done when: The program, rewards, limits, and environment are visible in one review.
10 MINAssign the people who must prove it
Name owners for program, commerce, identity, finance, security, operations, and customer support. One person may cover several roles.
Done when: Every production gate has a named owner and an approver.
5 MINPlan the first proof loop
Schedule one Sandbox purchase, one identical retry, one balance check, and one full or partial return before discussing production.
Done when: The team knows what will be tested, who will observe it, and what success looks like.

DEVELOPER HANDOFF

Give the technical owner decisions, not guesses.

A clear handoff shortens integration without pretending the merchant setup completed technical proof.

Program and environmentSandbox identifiers, approved rules, rewards, pending, and expiry
Customer identity and consentStable customer ID, enrollment state, matching, duplicates, deletion, and support access
Commerce evidenceOrder and return source references, amounts, channels, items, and event timing
Credential and reliability contractRequired Sandbox credential scope, idempotency keys, retry behavior, request IDs, signed outcomes, and alert owners
Proof casesFirst earn, identical retry, balance read, pending release, expiry, full return, and partial return
Launch boundariesNo client-side secret, no unapproved connector assumption, and no production customer runtime claim

Open developer documentation →

Ready to turn decisions into a Sandbox program?

The console is where your team records the plan. Keep production locked while you prove the full loop.

Open merchant console →

04 · CHOOSE A SHAPE

Six patterns. Start with one.

A pattern is a starting structure, not a promise of a particular result. Combine mechanics only when the customer story remains simple.

Everyday value

Best for: Frequent, easy-to-understand purchases
Start with: A clear earn rule and a small set of useful rewards
Watch: Do not let a large-looking point number hide weak customer value.

Tier recognition

Best for: Customers whose relationship grows over time
Start with: Few tiers, visible qualification, and benefits that feel different
Watch: Avoid permanent status promises unless the economics can support them.

Milestone benefits

Best for: Journeys with meaningful progress moments
Start with: One observable milestone and one relevant benefit
Watch: Reward the behavior you actually value, not activity that is easy to game.

Choice benefits

Best for: Members who value different perks
Start with: A small, controlled choice set at a clear eligibility moment
Watch: Define inventory, substitution, and reversal behavior before launch.

Referral loop

Best for: Programs with a trusted recommendation moment
Start with: A qualified referral event and transparent value for each party
Watch: Hold value until qualification and monitor linked identities and abuse.

Partner exchange

Best for: Two merchants with a deliberate shared proposition
Start with: A bilateral agreement, quoted conversion, caps, settlement, and reversals
Watch: The public API does not currently expose cross-program conversion.

05 · MOVE WITHOUT LOSING TRUST

A migration is a financial and customer promise transfer.

Never begin by deleting the old system. Preserve evidence, rehearse the move, explain every difference, and keep rollback possible.

1
Inventory
Document programs, statuses, balances, tiers, rewards, consent, expiration, exclusions, adjustments, and unresolved cases.
2
Map
Define how every source field and rule becomes a Loyumi record. Mark anything that cannot be translated automatically.
3
Rehearse
Import into Sandbox, reject malformed records, and repeat until the process is deterministic and explainable.
4
Reconcile
Compare member counts and control totals for available, pending, reserved, redeemed, expired, and adjusted value.
5
Approve
Record exceptions, customer communication, support scripts, cutover owner, rollback trigger, and finance sign-off.
6
Cut over
Freeze the agreed source window, run the proven process, verify control totals, observe real outcomes, and preserve both audit trails.

STOP

Do not launch with unexplained differences.

A small unexplained balance exception is still an exception. Assign it, resolve it, or explicitly approve its treatment.

KEEP

Preserve the evidence.

Retain source exports, mapping version, import results, rejected rows, reconciliation totals, approvals, and customer communication.

PROVE

Test the return path.

A migrated order, reward, or balance needs the same explainable reversal and support treatment as new activity.

06 · MEASURE HONESTLY

Give every number a definition and a cost.

Record the baseline before launch. Choose a time window, comparison method, channel scope, reward cost, and owner before interpreting movement.

Enrollment rate

Members who join ÷ eligible customers

Is the promise understandable and worth the small effort to join?

Active member rate

Members with a qualifying action ÷ enrolled members

Are enrolled people finding a reason to participate?

Repeat purchase

Members returning in a defined window

Is the program associated with durable behavior, not only sign-up?

Reward reach

Members who can use a meaningful reward

Is progress achievable before interest disappears?

Redemption rate

Value redeemed ÷ value made available

Are rewards relevant and usable without damaging margin?

Outstanding value

Issued value not yet settled, expired, or reversed

What obligation must finance monitor and reconcile?

Four rules for a credible review

1Compare against a recorded baseline or relevant control.
2Separate member selection from program impact.
3Include reward, discount, operational, and partner cost.
4Reconcile customer-facing totals to the ledger and finance view.

07 · EARN PRODUCTION

Production is an approval, not a button color.

Granular controls help expert teams move precisely. Safe defaults and required evidence keep less experienced teams from making an uncontrolled promise.

Program

Economics, rewards, limits, pending, expiration, and customer wording approved.

REQUIRED

Identity

Enrollment, consent, matching, duplicates, deletion, and support access tested.

REQUIRED

Commerce

Earn, retry, balance, full return, partial return, and ordering behavior proven.

REQUIRED

Migration

Opening records imported with no unexplained control-total difference.

REQUIRED

Finance

Liability treatment, settlement, expiry, adjustment, and reporting ownership approved.

REQUIRED

Risk & fraud

Velocity, referral, redemption, adjustment, identity, and partner-exchange abuse controls tested.

REQUIRED

Security

Least-privilege production credentials, rotation, monitoring, and incident containment ready.

REQUIRED

Operations

Alerts, runbooks, customer scripts, rollback, recovery, and named on-call owners ready.

REQUIRED

Approval

A second authorized operator reviews the current evidence before activation.

REQUIRED

08 · PARTNER VALUE

Yes, two merchants can agree to exchange value.

The obstacle is not the idea. The work is making the customer quote, funding, settlement, limits, reversals, and support correct every time.

Current product truth

The public Loyumi API does not expose a general cross-program point-conversion endpoint. Treat partner value exchange as a governed bilateral program design until a supported integration surface is explicitly published.

1Opt in
Each merchant approves the relationship, eligible programs, markets, and customer terms.
2Quote
Show the source amount, destination amount, ratio, expiry, and any limit before confirmation.
3Reserve
Hold source value and destination capacity so neither can be used twice during the exchange.
4Commit
Write linked ledger movements with one exchange reference and an idempotent outcome.
5Settle
Reconcile funded value, fees, exceptions, and merchant obligations on the agreed schedule.
6Reverse
Define cancellation, return, dispute, expiry, insolvency, and partner-exit behavior in advance.

The bilateral control sheet

Conversion ratio and roundingFunding and settlement currencyPer-member and program capsEligible balances and rewardsReservation and timeout rulesReturns and linked reversalsFraud monitoring and disputesCustomer disclosure and consentTax, accounting, and legal reviewPartner exit and value wind-down

09 · ASK PLAIN QUESTIONS

Frequently asked, honestly answered.

Open only what you need. Every answer separates what can be done now from what still requires proof or a published capability.

01Can we launch in less than an hour?

When your program inputs and console access are ready, you can create a clear Sandbox program plan and proof checklist in about 55 minutes. That is not a production launch. Production may take longer because identity, commerce, migration, reconciliation, security, and approvals must be proven.

02Do I need a developer?

Not to learn the model, choose a pattern, or configure the merchant-side program. A technical owner is normally needed to connect trusted commerce and identity systems through the documented HTTP API.

03Does Loyumi replace an existing program?

It is designed to support a governed replacement. Preserve the old system, map rules and identities, rehearse imports in Sandbox, reconcile totals, and keep a rollback plan until production evidence passes.

04Which connectors and SDKs are available?

This guide does not claim an official connector catalog or published JavaScript, iOS, or Android SDK. The documented integration surface is the server-side HTTP API. Confirm availability in developer documentation before planning around any package.

05Can customers use points at another merchant?

Yes, when both merchants deliberately agree to the ratio, customer experience, funding, limits, settlement, reversals, and support model. The current public API does not expose a general cross-program conversion endpoint.

06Can we use Widget Studio for our live storefront?

Widget Studio is currently a schema-driven, device-local design preview. It helps teams agree on intent, but it is not represented as a hosted production widget runtime.

07What happens when an order is returned?

Post the return against the original source reference. The system can calculate a bounded full or proportional clawback while keeping the original history visible.

08Who approves production?

Your authorized organization owners and operators do. Loyumi should support evidence and separation of duties; it does not replace your finance, privacy, security, or legal accountability.

09Should points expire?

There is no universal answer. Choose a disclosed rule that fits customer expectations, local requirements, program economics, and your ability to communicate reminders fairly.

10How do we avoid fake success?

Record the baseline before launch, define each metric and window, compare relevant cohorts, include reward and operating cost, and reconcile the ledger. A dashboard number without a definition is not evidence.

11Can we pause a program during an incident?

Yes. Pause the affected earning, redemption, campaign, credential, or production path while preserving ledger records and audit evidence. Do not delete history to make an incident disappear.

10 · SPEAK THE SAME LANGUAGE

Small glossary, fewer misunderstandings.

Use these meanings in requirements, reviews, support scripts, and launch evidence.

Available balance: Value a member can use now under the active program rules.
Campaign: A bounded change to the normal program for an audience, behavior, or period.
Clawback: A controlled reversal of previously issued value, usually linked to a return.
Environment: An isolated Sandbox or production space with its own records and credentials.
Expiration: The rule that ends the usability of value after a disclosed condition or date.
Idempotency: Protection that makes repeated delivery of one business fact produce one outcome.
Ledger: The evidence trail of value issued, held, redeemed, reversed, adjusted, and expired.
Member: A customer identity enrolled in a program with consent and program state.
Pending value: Value recorded but not yet available, often while a return or qualification window remains open.
Program: The core customer promise: earning, tiers, rewards, limits, pending, and expiration rules.
Reconciliation: Comparing commerce facts, ledger movements, and finance controls until differences are explained.
Reservation: A temporary hold that prevents the same value or inventory from being used twice.
Sandbox: A safe environment for configuration and proof without making a production promise.
Settlement: The agreed financial process that makes merchants whole after partner value is used.
Source reference: The stable order, return, or business-event identifier shared between systems.

YOUR NEXT RIGHT-SIZED STEP

Configure in the console. Integrate from the developer docs.

Keep the customer promise simple, the evidence inspectable, and production earned.