Display raffles
Show available raffles, prize details, and the buyer's entries.
List and detail
Use GET /raffles to list the raffles attached to your platform. Pagination uses limit (1–100, default 50) and offset (default 0).
Fetch GET /raffles/{raffleId} for a raffle's prizes, images, price, results, and payment parameters. An unavailable or inaccessible raffle returns 404 RAFFLE_NOT_FOUND.
| Field | Suggested display |
|---|---|
name, description | Raffle heading and description |
ticket_price_usd | Price per ticket; returned as a decimal string |
start_time, end_time | Opening time and countdown |
prizes | Prize gallery and draw results |
tickets_sold, max_total_entries | Entries sold and capacity, when capped |
status | Raffle state |
sales_enabled | Whether your platform can start new purchases |
Enable purchases only while live
| Status | Buyer experience |
|---|---|
scheduled | Show the opening time. A scheduled raffle may be listed before its detail is available. |
live | Allow new checkouts only when sales_enabled is true. |
closed | Stop new purchases. Results may still be pending. |
completed | Show the results. |
cancelled | Show cancellation and the buyer's refund status separately. |
A closed raffle can be extended and return to live. Refresh its details when you receive raffle.live or raffle.closed.
Partners can be added or have new sales stopped before drawing begins. If sales_enabled is false, show “New entries paused”. Keep existing checkouts available until their original deadline, and continue showing tickets, results and refunds. Earlier sales remain attributed to the original partner.
Refresh raffle details before checkout and handle 409 RAFFLE_SALES_DISABLED if sales stop while the buyer is on the page.
Availability is a display hint
Ticket totals are shared across all storefronts selling the raffle. Active reservations can also consume capacity. Treat the displayed remaining count as advisory; only a successful checkout reserves tickets.
Poll the currently viewed raffle at a modest interval, pause in hidden tabs, and back off after errors. Handle sold-out or closed responses as normal outcomes.
Show the buyer's position
GET /raffles/{raffleId}/users/{externalUserRef} returns your buyer's confirmed ticket count and odds_pct. An unknown buyer returns zeros.
per_wallet_limit is applied within your platform. Do not describe it as a global limit per person.