The words we use¶
The big picture¶
A venue runs events. An event sells ticket types, and it can also sell tables through seating areas. A guest who buys tickets has an order. A guest who books a table has a reservation. At the door, staff check in the guest. Money can come back as a refund, or the bank can raise a dispute.
Venue¶
A place that uses Speakeasy, such as a club, bar or restaurant. Each venue has a time zone and a business start time. A venue's business day starts at that time, so a Saturday night event that runs past midnight still belongs to Saturday.
Event¶
A dated happening at a venue. An event has two ids, and it pays to keep both:
| Id | Looks like | Used by |
|---|---|---|
id |
a UUID | The API, and the links between records |
uniqueId |
EVE-ABC123 |
Public links, and some venue routes |
An event can be a draft or published (version), and it can be turned on or off
(status). Members-only and discounted events are not on the public lists.
Ticket type¶
One kind of ticket for an event, such as General Admission or VIP. In the data it is an
eventTicket, and its name is tierName. A ticket type has:
- A
price, in the venue's currency, before fees and tax. - A sale window,
beginSaletoendSale. - Stock:
issuedUnits, andsoldUnits, which also counts tickets held in checkouts (inCartUnits).
Some ticket types are not for everyone. isProtected needs a password, isMembersOnly is
for members, and sellingPaused is paused by the venue. Do not show these as on sale.
Add-on¶
A ticket type with isAddOn set to true, offered alongside the tickets. It is bought and
stored like any other ticket type.
Seating area¶
A kind of table at an event, such as Main Floor or Skybox. A venue has template areas, and
each event has its own copy with its own prices and stock. availableInventory tells you
how many tables can be booked now.
A seating area can be booked online, take requests, or both. availability in the search
answer tells you which.
Time slot¶
Some seating areas are sold by arrival time. For those, requiresTimeSlotSelection is
true, and price and stock sit on each entry in timeSlots, not on the seating area itself.
Table tier¶
A seating area can have price steps. The tables in the first tier sell at one price, and when they are gone the next tier applies. The search answer always shows the price of the tier on sale now.
Minimum spend¶
What a party agrees to spend at the venue for the table. It is not charged online. A
seating area includes a number of guests in the minimum, and can add an amount for each
extra guest (guestPricing). Use guestCount in the search to get the minimum for a real
party size.
Deposit¶
What the guest pays online to hold the table. It can be a flat amount or a percentage of
the minimum (depositType). Some areas let the guest pay the whole minimum up front
instead.
Spend agreement¶
The full picture for the night: the minimum with its fees and tax, and what is left to pay
at the venue after the deposit (balanceDueAtVenue).
Order, reservation and request¶
These three are easy to mix up.
| Word | What it is | In the data |
|---|---|---|
| Order | Tickets someone bought or was given. bookingType is EVENT, or COVER for a door cover charge. Comps and free tickets are orders too, see bookingSubType. |
Booking, with one bookingHasItem per ticket |
| Reservation | A table for a party on a date. Staff can create it, or a guest can book it online. | Reservation, and a tableBooking when it was paid online |
| Request | A guest asks a venue for a table, and the venue answers. | A Reservation that starts with reservationStatus REQUESTED. See the warning. |
A paylink is a payment link that staff send a guest for a reservation.
The word "booking" in our field names usually means an order. tableBooking means the
online payment for a table.
Guest¶
A person. A guest has one record across Speakeasy (consumerUser) and one relationship per
venue (venueHasCustomer). The relationship holds what that venue knows, such as visits and
total spend, and whether the guest has opted out.
Guest data is personal data. Only store the fields you need, and keep them safe.
Check-in¶
Staff scan the guest's QR code or find them in the door app. One QR code covers the whole order, and each ticket is checked in on its own.
The routes do not return ticket check-ins today. Reservations do carry checkInAt,
seatedAt and checkInGuests.
Refund¶
Money going back to the guest. For a ticket there are two kinds, shown in refundType on
the ticket:
refundType |
What it means |
|---|---|
NONE |
Not refunded |
FULL |
Refunded. The ticket stays valid. |
FULL_VOID |
Refunded and voided. The ticket goes back on sale. |
Dispute¶
The guest's bank questions a charge. The venue can answer with evidence, and the bank decides. See the status list.
Concierge entry¶
A conversation from a chat or text service, sent to the venue team to follow up. See Send us Concierge entries.
Guest list entry¶
A name on a venue's guest list for one business date, with a number of guests. It is not an order and not a reservation. See Send us a guest list.