Run a raffle end to end

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

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
  }'

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;

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"]

Want artwork? Attach an image with POST /raffles/{id}/image — see the images guide.

2. Manage while it runs

# 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:

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

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:

# 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

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!

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.

Prefer to just ask an AI?

With the 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.”

Getting Started

Guides

Run a raffle end to end

1. Create the raffle

2. Manage while it runs

3. End it — the draw happens automatically

4. Review the winners

5. Confirm — winners are notified

Prefer to just ask an AI?

​1. Create the raffle

​2. Manage while it runs

​3. End it — the draw happens automatically

​4. Review the winners

​5. Confirm — winners are notified

​Prefer to just ask an AI?

1. Create the raffle

2. Manage while it runs

3. End it — the draw happens automatically

4. Review the winners

5. Confirm — winners are notified

Prefer to just ask an AI?