About the Ticket Reservations API

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.

Reservation lifecycle

Understanding the reservation lifecycle is essential for effective implementation:

1. When a site visitor selects tickets, reservations start in PENDING status with an automatic expiration time (typically 5-30 minutes based on event settings, the reservationDurationInMinutes field).
2. Tickets are held exclusively for the site visitor who is redirected to the checkout. Other visitors can't purchase these specific tickets.
3. Reservations resolve in one of several ways:
   • Confirmed: Payment completion changes status to CONFIRMED, securing tickets permanently.
   • Cancelled: Manual cancellation or payment failure changes status to CANCELED_MANUALLY or CANCELED. Tickets are immediately released back to available inventory.
   • Expired: Automatic expiration after the time limit changes status to EXPIRED. Tickets are immediately released back to available inventory.

Before you begin

It's important to note the following points before starting to code:

• A site must have Wix Events & Tickets installed.
• The API requires existing ticket definitions. Create events and ticket types using the Wix Events V2 and Ticket Definitions V2 APIs first.
• Advanced reservation settings like bypassing availability limits should be used cautiously to prevent overselling.

Use cases

• Reserve tickets and process payments

Terminology

• 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 V2 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.