> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rigaly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a raffle end to end

> Create a raffle, watch entries come in, end it, review the drawn winners, and confirm

Raffles let customers spend points on entries for a prize draw. The full lifecycle runs through the API:

```
create → (customers enter in the app) → end (draw) → review winners → confirm → completed
```

Two things the platform handles for you:

* **The draw is automatic and fair.** When the raffle ends — at `ends_at`, or immediately when you call the end endpoint — Rigaly draws one *provisional* winner per slot (distinct customers). You never pick the initial winners by hand; you *review* the draw.
* **Cancelling refunds everyone.** `POST /raffles/{id}/cancel` returns all entry points to participants.

## 1. Create the raffle

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.rigaly.com/api/v1/raffles \
    -H "Authorization: Bearer rgly_sk_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Espresso Machine Giveaway",
      "description": "Win a La Marzocco Linea Mini for your home.",
      "terms_conditions": "One prize. Winner announced Sept 1. Must be 18+.",
      "ends_at": "2026-08-31T23:59:59Z",
      "points_cost": 200,
      "entries_per_user": 10,
      "winners_count": 1
    }'
  ```

  ```javascript Node.js theme={null}
  const RIGALY = { Authorization: `Bearer ${process.env.RIGALY_API_KEY}` };

  const { data } = await fetch("https://api.rigaly.com/api/v1/raffles", {
    method: "POST",
    headers: { ...RIGALY, "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Espresso Machine Giveaway",
      description: "Win a La Marzocco Linea Mini for your home.",
      terms_conditions: "One prize. Winner announced Sept 1. Must be 18+.",
      ends_at: "2026-08-31T23:59:59Z",
      points_cost: 200,       // points per entry (0 = free raffle)
      entries_per_user: 10,   // omit or null = unlimited
      winners_count: 1,
    }),
  }).then((r) => r.json());

  const raffleId = data.raffle.id;
  ```

  ```python Python theme={null}
  import os, requests

  RIGALY = {"Authorization": f"Bearer {os.environ['RIGALY_API_KEY']}"}

  raffle = requests.post(
      "https://api.rigaly.com/api/v1/raffles",
      headers=RIGALY,
      json={
          "name": "Espresso Machine Giveaway",
          "description": "Win a La Marzocco Linea Mini for your home.",
          "terms_conditions": "One prize. Winner announced Sept 1. Must be 18+.",
          "ends_at": "2026-08-31T23:59:59Z",
          "points_cost": 200,
          "entries_per_user": 10,
          "winners_count": 1,
      },
  ).json()["data"]["raffle"]
  ```
</CodeGroup>

Want artwork? Attach an image with `POST /raffles/{id}/image` — see the [images guide](/guides/images).

## 2. Manage while it runs

```bash theme={null}
# Live status with entry counts
curl https://api.rigaly.com/api/v1/raffles/{raffleId} \
  -H "Authorization: Bearer rgly_sk_YOUR_KEY"

# Who has entered
curl https://api.rigaly.com/api/v1/raffles/{raffleId}/entries \
  -H "Authorization: Bearer rgly_sk_YOUR_KEY"

# Edit details (restrictions apply once entries exist)
curl -X PATCH https://api.rigaly.com/api/v1/raffles/{raffleId} \
  -H "Authorization: Bearer rgly_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Now with free shipping to the winner!"}'

# Pause entries temporarily (open | paused | hidden)
curl -X POST https://api.rigaly.com/api/v1/raffles/{raffleId}/availability \
  -H "Authorization: Bearer rgly_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"availability": "paused"}'
```

## 3. End it — the draw happens automatically

Let the raffle reach `ends_at` (Rigaly ends it and draws on schedule), or close it early:

```bash theme={null}
curl -X POST https://api.rigaly.com/api/v1/raffles/{raffleId}/end \
  -H "Authorization: Bearer rgly_sk_YOUR_KEY"
```

Either way, provisional winners are drawn immediately — one distinct customer per slot.

## 4. Review the winners

```bash theme={null}
curl https://api.rigaly.com/api/v1/raffles/{raffleId}/winners \
  -H "Authorization: Bearer rgly_sk_YOUR_KEY"
# → [ { "slot": 1, "status": "provisional", "user": { ... }, ... } ]
```

Not happy with a draw? Before confirming you can:

```bash theme={null}
# Redraw a slot randomly
curl -X POST https://api.rigaly.com/api/v1/raffles/{raffleId}/winners/1/reroll \
  -H "Authorization: Bearer rgly_sk_YOUR_KEY"

# Or set a specific entry as the winner (entry_id from the entries endpoint)
curl -X PUT https://api.rigaly.com/api/v1/raffles/{raffleId}/winners/1 \
  -H "Authorization: Bearer rgly_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entry_id": "ENTRY_UUID"}'
```

## 5. Confirm — winners are notified

```bash theme={null}
curl -X POST https://api.rigaly.com/api/v1/raffles/{raffleId}/winners/confirm \
  -H "Authorization: Bearer rgly_sk_YOUR_KEY"
```

This completes the raffle and notifies every winner in the app. Done!

<Note>
  **If a confirmed winner never shows up** to claim the prize: `POST /winners/{slot}/replace` forfeits them and draws a provisional replacement, then `POST /winners/{slot}/confirm` locks in the new winner.
</Note>

## Prefer to just ask an AI?

With the [AI connector](/guides/ai-connector): *"Start a raffle for an espresso machine, 200 points per entry, ends August 31st"* → *"End the raffle and show me the winners"* → *"Confirm the winners."*