The Ticket Reservations API lets you hold tickets for a specified time period during the checkout process. When visitors select tickets for an event, the system creates reservations to prevent other customers from purchasing the same tickets while the original customer completes their purchase. The API also provides advanced reservation settings, such as the ability to bypass availability limits.
With the Ticket Reservations API, you can complete the following tasks:
- Create time-limited ticket reservations.
- Delete a ticket reservation from the system records.
- Retrieve a reservation, which is useful to track reservation counts and ticket availability across events.
- Cancel a ticket reservation to change a reservation status to
CANCELED_MANUALLY.
Understanding the reservation lifecycle is essential for effective implementation:
- When a visitor selects tickets, reservations start in
PENDING status with an automatic expiration time (typically 5 to 30 minutes based on event settings, the reservationDurationInMinutes field).
- The system holds tickets exclusively for the visitor who goes to checkout. Other visitors can't purchase these specific tickets.
- Reservations resolve in one of several ways:
- Confirmed: Payment completion changes the status to
CONFIRMED, securing tickets permanently.
- Canceled: Manual cancellation or payment failure changes the status to
CANCELED_MANUALLY or CANCELED. Tickets are immediately released back to the available inventory.
- Expired: Automatic expiration after the time limit changes the status to
EXPIRED. Tickets are immediately released back to the available inventory.
It's important to note the following points before starting to code:
- The site must have Wix Events & Tickets installed.
- The API requires existing ticket definitions. Create events and ticket types using the Events V3 and Ticket Definitions V3 APIs first.
- Advanced reservation settings like bypassing availability limits should be used cautiously to prevent overselling.
- Ticket Reservation: a temporary hold on specific tickets for a limited time period during checkout.
- Ticket Definition: the template or type of ticket (for example, 'General Admission', 'VIP') defined at the event level. For more information, see the Ticket Definitions V3 API.
- Line Item: an individual entry in a reservation representing tickets of the same type, price, and seating.
- Expiration Time: the date and time when a
PENDING reservation will automatically expire and release tickets.
- Guest Price: custom pricing set by customers for 'pay-what-you-want' or donation-style tickets.
- Pricing Option: different price tiers for the same ticket type (for example, 'Early Bird', 'Regular').
- Seat Assignment: specific seat locations for assigned seating events (section, row, seat number).
- Service Fee: additional fees applied by Wix for payment processing and platform usage.