When configuring an event in Opendate, an organizer is allowed to configure 3 parameters:
- The total capacity of the venue (venue_capacity attribute of Confirm)
- The total number of tickets available for each TicketType
- The total number of times a promo code is available to be used
In order to enforce these limits, Opendate must be aware of past ordering activity (sold number of tickets and promo code redemptions), but also orders that are currently in progress. This is where the Ticket Reservation system comes into play.
The Ticket Reservation system represents the user’s claim to purchase tickets or use a promo code. Similarly to the Ordering system, Ticket Reservations can be built in order to see the total cost of the order (including any fees or discounts). Once the user has entered the number of tickets they want and the promo code, then the Ticket Reservation can be created.
Once created, the user has 8 minutes in order to place their order before the tickets are released for someone else to purchase. After 8 minutes, the Ticket Reservation expires and can no longer be used. Currently, we do not enforce ticket or promo code limits. However, this system is being deployed in order to make this possible.
During the checkout process, a Ticket Reservation can be updated with the person’s first and last name and email address (this is optional). If the user cancel’s their order, the Ticket Reservation should be deleted so that Opendate knows that those tickets have been released for someone else to purchase.
Credit card Ticket Reservation records will provide the “stripe_client_secret” value, which is needed in order to collect payment from the user with Stripe. Regardless of payment method (credit card or cash), once the user finalizes their order and submits it, the Ticket Reservation must be completed. Under the hood, this creates an Order record, which then creates tickets. The complete endpoint can be called directly (using a POST OR GET request), or it can be used as the “redirect_url” for the Stripe integration (using a GET request). Completing the Ticket Reservation allows Opendate to know that the payment process has been started, and the order was not abandoned (allowing us to determine how many tickets have been sold).
The goal of the Ticket Reservation system was to have an API interface as close to the Order interface as possible to require minimum changes for the iOS app. Once we’ve converted to this system, we will remove the “Organizer Orders” endpoints.
Build / Create Optional Parameters
The following optional parameters work on both the BUILD and CREATE endpoints:
| Name | Description | Note |
| should_send_ticket_email | The default value is false. This determines if the email receipt (including tickets) will be sent to the customer’s email address at the time the order is placed.Normally, orders placed at the door using the iOS app would not send a receipt to the customer. However, this is useful for orders placed in the future (example: The box office sells a ticket for next week) | Warning: If the value is true, then first_name, last_name, and email values are required at the time of completion. This is required information in order to send the receipt email. |
| complimentary | The default value is false. If true, then the order total will always be $0.This is useful when the box office does their promotional activities. They may want to order a bunch of tickets that they can give away to promote the show. | It is possible for an order to have both a promo_code AND be complimentary.In this scenario, the promo_code could have been used to reveal a hidden Ticket Type.Depending on the team’s configured Fee Rules, it is still possible for a 100% off promo_code to require payment for fees. Complimentary orders never require any payment. |
| promo_code_name | The name of the promo code the user would like to redeem. The promo code will only be redeemed if it is valid at the time the order is submitted (the current time is past the start_time, the current time is not past the end_time, and we have not passed the limit of usages for the code). | When the server finds the promo code from the provided name, we use the exact same logic as the “Promo Code Lookup” endpoint. So, if the Lookup endpoint returns data for the promo code name, the promo code is valid and will be found. |
| add_on_order_items_attributes | If the customer chooses to buy AddOns, pass this attribute when building or creating a TicketReservation. For each AddOn being purchased, we need to know the AddOn ID and quantity being purchased. | See below for an example of how to send this data to the server |
Here is an example of a request data payload when the customer is also buying AddOns:
{
"ticket_reservation": {
"promo_code_name": "",
"complimentary": false,
"order_items_attributes": [
{
"ticket_type_id": 1,
"quantity": 3
}
],
"add_on_order_items_attributes": [
{
"add_on_id": 1,
"quantity": 3
}
],
}
}