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,
    "max_entries": 500,
    "max_entries_mode": "total"
  }'

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,   // per customer — omit or null = unlimited
    winners_count: 1,
    max_entries: 500,       // whole raffle — omit or null = unlimited
    max_entries_mode: "total", // "total" entries | unique "participants"
  }),
}).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,
        "max_entries": 500,
        "max_entries_mode": "total",
    },
).json()["data"]["raffle"]

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

Cap the size of the raffle

A raffle has two independent ceilings. entries_per_user limits one customer; max_entries limits the whole raffle. Both default to null, which means unlimited. max_entries_mode decides what the ceiling counts:

Mode	Counts	Use it when
`total` (default)	Every entry, whoever bought it	The prize pool is fixed — “500 tickets, then we draw”
`participants`	Distinct customers	You’re capping people, not tickets — “the first 200 customers, each with up to 10 entries”

// 500 tickets total, however they're distributed
{ "max_entries": 500, "max_entries_mode": "total" }

// 200 people max; each can still buy up to entries_per_user tickets
{ "max_entries": 200, "max_entries_mode": "participants" }

A full raffle is not a closed raffle. At the ceiling it stays active and visible in the app, and it still draws its winners at ends_at — only new entries are blocked. Customers see it marked as full, and an attempt to enter comes back as RAFFLE_FULL:<remaining> (the suffix is how many entries would still have fit, so the app can say “only 2 spots left”). Read how full it is from the raffle list, which carries live counts:

curl https://api.rigaly.com/api/v1/raffles \
  -H "Authorization: Bearer rgly_sk_YOUR_KEY"
# → { "max_entries": 500, "max_entries_mode": "total",
#     "total_entries": 500, "unique_entrants": 168,
#     "entries_remaining_global": 0, "is_full": true, ... }

GET /raffles/{id} returns the same four figures for a single raffle. Read is_full rather than comparing counts yourself — it already knows whether max_entries_mode is counting entries or distinct entrants, and entries_remaining_global is measured in the same unit. On an uncapped raffle the pair is null / false. Raising the cap reopens entries immediately, with no other change to the raffle:

curl -X PATCH https://api.rigaly.com/api/v1/raffles/{raffleId} \
  -H "Authorization: Bearer rgly_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_entries": 750}'   # or null to remove the ceiling entirely

Once a raffle has entries, max_entries_mode is locked along with points_cost, entries_per_user and winners_count (FIELDS_LOCKED) — customers paid for the odds they were shown, so what the ceiling counts can’t change underneath them. max_entries itself stays editable, but only upward: lowering it below the entries already recorded returns MAX_ENTRIES_BELOW_CURRENT.

2. Manage while it runs

# Live status with entry counts (total_entries, unique_entrants,
# entries_remaining_global, is_full)
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

Cap the size of 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

​Cap the size of 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

Cap the size of 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?