> For the complete documentation index, see [llms.txt](https://help.openloyalty.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.openloyalty.io/implementation-guide/module-checklists/fortune-wheels-and-lotteries.md).

# Fortune Wheels & Lotteries

Spins and prize draws: members buying a spin, campaigns awarding spins that still need drawing, pay-to-enter prize draws from the catalogue, detecting a win, and fulfilling prizes.

A fortune wheel is a reward whose outcome is drawn: the member gets a spin, Open Loyalty draws a result by probability, and a win issues units, a coupon or a prize. The same mechanism powers lotteries — "scan a code for a chance to win", "spend 100 points to enter the draw for a bag".

**For the basic flow — a member buying and spinning a wheel — follow the User Guide's** [**fortune wheel implementation checklist**](https://help.openloyalty.io/gamification/fortune-wheels/implementation-checklist) (buy → draw → fetch the result). This page adds the patterns around it: spins awarded by campaigns, pay-to-enter prize draws, detecting a win and fulfilling prizes. See also [How probability works](https://help.openloyalty.io/gamification/fortune-wheels/how-probability-works).

## Who does what

| Area                  | Responsibility                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Admin Panel**       | Wheels with prizes and probabilities, costs, limits; campaigns that give spins; prize rewards and their stock |
| **Integration layer** | Buys spins and entries, finds undrawn spins, draws them, interprets the result                                |
| **Website / app**     | The wheel or draw animation and the win or "try again" screens                                                |
| **Fulfilment / CRM**  | Ships physical prizes; tells winners                                                                          |

## Design decisions

| Decision                     | Options                                                            | Recommendation                                                                                                                                                                                                                    |
| ---------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| How members get spins        | Buy with units, or awarded by campaigns                            | Both work with the same wheel. Awarded spins need an extra step: they're issued undrawn and must be drawn.                                                                                                                        |
| When to draw an awarded spin | Immediately in the integration, or when the member opens the wheel | When the member opens it, if the animation is part of the fun; immediately (server-side) if the member never sees a wheel.                                                                                                        |
| Units won at random          | Fixed amounts, or a wheel with several amounts                     | A wheel with amounts and probabilities — the campaign effect gives a spin instead of units.                                                                                                                                       |
| Catalogue prizes as draws    | Direct purchase, or "enter the draw"                               | For scarce prizes, a pay-to-enter wheel per prize: each entry costs units, a win issues the prize reward. Link the prize to its wheel with a label (e.g. `draw_reward_id`) so the catalogue can show the prize and buy the entry. |
| Limits                       | None, per member, per period, prize stock                          | Set reward limits on high-value prizes — a spin can't win a prize that's out of stock or over its limit.                                                                                                                          |

## Recommended flow

{% stepper %}
{% step %}

### Configure (Admin Panel)

Create the wheel with its prizes and probabilities, and the prize rewards themselves (with stock). For awarded spins, add a campaign or challenge effect that gives the wheel. Keep wheels out of the regular catalogue with `type[notIn]=fortune_wheel` where needed.
{% endstep %}

{% step %}

### Buy a spin or an entry

`POST /api/{storeCode}/reward/{reward}/buy` with the member's `customerId`, `quantity = 1`. Units are spent and an issued reward (`issuedRewardId`) is returned, not yet drawn.
{% endstep %}

{% step %}

### Find awarded spins

Spins given by campaigns appear as undrawn redemptions: `GET /api/{storeCode}/redemption?customerData:loyaltyCardNumber={id}&rewardType=fortune_wheel&fortuneWheelStatus:drawnAt[notHasValue]&_orderBy[redemptionDate]=asc`.
{% endstep %}

{% step %}

### Draw — once

`POST /api/{storeCode}/redemption/{issuedRewardId}/draw`. Each issued spin can be drawn only once. On `409` or `503`, retry the **same** `issuedRewardId` with backoff — never buy a new spin to replace it.
{% endstep %}

{% step %}

### Read the result

The response's `fortuneWheelStatus.effects[]` lists what was given. **A win is an effect with `status.code = "success"`** — don't decide by the rule name. A won prize is issued like any reward: physical prizes as pending redemptions for fulfilment, vouchers with the next code.
{% endstep %}

{% step %}

### Fulfil prizes

Ship physical prizes as in [Rewards & coupons](https://help.openloyalty.io/implementation-guide/module-checklists/rewards-and-coupons.md) — from the `CustomerBoughtReward` webhook, or in batches with a `rewardFulfillment` [export](https://help.openloyalty.io/integrations-and-data-exchange/imports-exports/exports) — and update their status.
{% endstep %}
{% endstepper %}

## Sequence diagram

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-640c9e01c15c55d1313fefaa9ba559a7d67c86a4%2Fig-fortune-wheels-lotteries.png?alt=media" alt="Spin awarded by a campaign: member activity triggers a campaign effect that gives an undrawn spin; when the member opens their spins, the integration layer lists undrawn fortune wheel redemptions; when the member spins, it draws one and reads effects status codes — a win is an effect with status code success, not the rule name. Prize draw from the catalogue: the member enters the draw; the integration layer buys the lottery reward with customerId and quantity 1, units are spent, and the returned issued reward is drawn; a win issues the prize, physical as pending for fulfilment or a voucher with the next code. On 409 or 503 the draw is retried with the same issuedRewardId, never by buying a new entry." width="728"><figcaption><p>Awarded spins and catalogue prize draws</p></figcaption></figure>

## Go-live checklist

### Admin Panel

* [ ] Probabilities add up as intended and have been reviewed by the business.
* [ ] High-value prizes have stock and reward limits.
* [ ] Campaigns that give spins have per-member limits.

### Integration layer

* [ ] Awarded spins are found with the undrawn-redemptions query and drawn exactly once.
* [ ] Draw failures are retried on the same `issuedRewardId`; no extra entries are bought.
* [ ] Wins are detected by `effects[].status.code = "success"`.
* [ ] Physical prizes reach fulfilment.

### Website / app

* [ ] The animation shows the result returned by Open Loyalty — it never decides the result itself.
* [ ] A member with undrawn spins can find and use them.

### Validation

* [ ] Over many test draws, the outcome distribution roughly matches the configured probabilities.
* [ ] An out-of-stock prize can't be won.
* [ ] A failed draw retried later gives one result, not two.

## Key endpoints

* `POST /api/{storeCode}/reward/{reward}/buy` — [Buy a reward](https://help.openloyalty.io/api-reference/reward/buy-a-reward)
* `GET /api/{storeCode}/redemption` — [Get redeemed rewards list](https://help.openloyalty.io/api-reference/reward/get-redeemed-rewards-list) (`rewardType=fortune_wheel`, `fortuneWheelStatus:drawnAt[notHasValue]`)
* `POST /api/{storeCode}/redemption/{issuedReward}/draw` — [Draw a reward from the fortune wheel](https://help.openloyalty.io/api-reference/reward/draw-a-reward-from-the-fortune-wheel)
* `POST /api/{storeCode}/export/{type}` — [Create an export](https://help.openloyalty.io/api-reference/export/create-an-export) (`rewardFulfillment`)

**Webhooks:** [CustomerBoughtReward](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/CustomerBoughtReward), [CampaignEffectWasApplied](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/CampaignEffectWasApplied)

{% hint style="warning" %}
**Common pitfalls**

* Giving spins from campaigns and never drawing them: members see nothing.
* Deciding win or lose by the rule name instead of the effect status.
* Retrying a failed draw by buying a new spin — the member pays twice.
* Letting the front-end animation pick the result.
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.openloyalty.io/implementation-guide/module-checklists/fortune-wheels-and-lotteries.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
