Implementation Checklist

Use this checklist to prepare, integrate, and validate your Fortune Wheel before launch.

Overview

Use this checklist to prepare your Fortune Wheel for launch.

It covers three areas:

• Configuration in the Admin Panel

• Backend integration flow

• Frontend handling and final validation

Use it together with Creating Fortune Wheels, Managing Fortune Wheels, and How Probability Works.

Open Loyalty returns wheel data and draw results. Your application is responsible for the wheel UI, animation, and post-spin experience.

---

Recommended implementation flow

1

Configure the wheel

Create the Fortune Wheel in the Admin Panel.

Make sure you:

• Add all winning and non-winning fields

• Assign correct probability values

• Define visibility, availability, and targeting

• Set redemption and budget limits

If you need help with setup, follow Creating Fortune Wheels.

2

Render the result in your app

Use GET /api/{storeCode}/reward/{id} to load the wheel definition.

Map the returned labels and rules to your visual slices.

3

Create the spin entry

Call POST /api/{storeCode}/reward/{reward}/buy.

This creates a unique redemption entry for a single spin.

Store the returned issuedRewardId. You need it for the draw request and result lookup.

4

Trigger the draw

Call POST /api/{storeCode}/redemption/{issuedRewardId}/draw.

This endpoint performs the random draw based on the configured wheel rules.

Each issuedRewardId can be drawn only once.

5

Confirm the prize outcome

Use GET /redemption/{issuedRewardId} to load the final redemption details.

After the draw:

• Stop the animation on the returned result

• Show a winning state when effects are present

• Show a "Better luck next time" state when no effect is returned

If the reward grants units, you can also refresh the member wallet view to show the updated balance.

---

Sequence Diagram

Configuration Phase:

Spin Phase:

---

Go-live checklist

1. Admin Panel setup

• The Fortune Wheel is created and saved.

• Each prize field has a clear label.

• Winning fields are linked to the correct reward or units effect.

• Non-winning fields are configured for "no win" outcomes.

• Total probability across all fields equals 100%.

• Visibility and availability are set correctly.

• Targeting matches the intended audience.

• Member usage limits are configured.

• Global limits or budget limits are configured if needed.

• The wheel is active and ready for use.

2. Backend integration

• Your app calls POST /api/{storeCode}/reward/{reward}/buy before each spin.

• The returned issuedRewardId is stored securely.

• Your app calls POST /api/{storeCode}/redemption/{issuedRewardId}/draw only once per issued reward.

• The backend does not expose a way to repeat the same draw.

• Error handling is implemented for expired, invalid, or already-used entries.

• Authentication and permissions are configured for all used endpoints.

3. Frontend experience

• Your app loads wheel labels and structure from GET /api/{storeCode}/reward/{id}.

• Your app loads spin results from GET /api/{storeCode}/redemption/{issuedRewardId}.

• The number of visual slices matches the configured wheel rules.

• The animation starts only after a valid spin entry exists.

• The animation stops on the correct result returned by the draw endpoint.

• A dedicated state exists for "no win" results.

• A dedicated state exists for winning results.

• Prize details are shown after the draw.

• Updated points or coupon data are refreshed after redemption.

4. Final validation

• Test at least one winning scenario.

• Test at least one "no win" scenario.

• Test member limits such as daily or total spin limits.

• Test visibility and targeting rules.

• Test what happens when the budget or availability limit is reached.

• Confirm the post-spin state matches the returned API data.

---

Key endpoints

• GET /reward?type[eq]=fortune_wheel — list available Fortune Wheels

• GET /reward/{id} — get wheel rules and labels for rendering

• POST /reward/{reward}/buy — create a single spin entry

• POST /redemption/{issuedRewardId}/draw — perform the draw

• GET /redemption/{issuedRewardId} — fetch the final redemption result

The safest flow is always: buy → draw → fetch result.