Overview
The Waiting List API provides endpoints for managing event waiting lists, queue positions, and time-limited ticket offers. When tickets sell out, users can join a waiting list and receive automatic offers when tickets become available.Key Features
- Automatic Queue Management: Users are automatically offered tickets when spots become available
- Time-Limited Offers: Ticket offers expire after 30 minutes if not purchased
- Rate Limiting: Prevents abuse with 3 joins per 30 minutes per user
- Real-Time Position Tracking: Query current queue position at any time
Waiting List Status Flow
Status Values
Current status of the waiting list entry
waiting- User is in queue waiting for a ticketoffered- User has an active ticket offer (30 minute expiration)purchased- User successfully purchased the ticketexpired- Ticket offer expired without purchase
Rate Limiting
To prevent abuse, thejoinWaitingList mutation enforces rate limits:
- Rate: 3 joins per user
- Window: 30 minutes (fixed window)
- Scope: Per user ID across all events
Offer Expiration
Ticket offers automatically expire after 30 minutes (DURATIONS.TICKET_OFFER). This is the minimum duration allowed by Stripe for checkout sessions.
When an offer expires:
- The waiting list entry status changes to
expired - The queue is automatically processed
- The next user in line receives an offer
Available Endpoints
Join Waiting List
Add user to event waiting list with automatic offer if available
Get Queue Position
Query user’s current position in the waiting list
Process Queue
Internal endpoint to process queue and create offers
Related Resources
- Events API - Manage event capacity and availability
- Tickets API - Purchase and manage tickets
- Rate Limiting - Understanding rate limit policies