About Ticket Definitions v3

With the Ticket Definitions API, you can create definitions for tickets. A definition includes the following ticket settings:

• Fee type. Determine whether the fee will be paid by a guest or a seller.
• Pricing. Define different ticket prices based on factors such as early bird discounts, VIP packages, group rates, or special promotions. Several pricing methods are available for you to select from: Fixed price, Guest price, Free. Additionally, you can customize prices for different groups of people using Price options.
• Availability. Set the ticket limit available to buy. Also, you are able to check number of purchased or reserved tickets.
• Sale period. Set the sale start and end dates. Also, when defining the sale period, it is possible to choose to display event tickets to customers even before the sale starts.

Before you begin

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

• Install the Wix Events & Tickets app from Wix App Market.
• Ticket definition is not the same as ticket. Ticket definitions are used to define settings for a set of tickets. After paying for selected tickets, the Checkout API automatically generates the ticket.

Use cases

• Add a specific-price ticket counter for an event
• Sync ticket definitions with external ticketing system
• Notify when tickets go on sale

Terminology

• Pricing method: Different pricing methods are available for an event:
  • Fixed price: All tickets in the same definition are sold at the exact same price, regardless of when they are purchased or other factors.
  • Guest price: A minimum price a guest must pay for a ticket. For example, money goes to donation.
  • Price options: All tickets in the same ticket definition are priced at different rates, such as different prices for adults, children, and students.
• Ticket availability: The status of ticket inventory, indicating whether tickets are available or sold out. This type can also include availability limits and timeframes for ticket sales.
• Sale period: Duration of time during which event tickets are available for purchase.
• Event Dashboard: Control center in the Wix site UI for managing site event settings and features.

Ticket Definitions v3: Supported Filters and Sorting

The following table shows field support for filters and sorting for the Ticket Definition object:

Field	Query Filter Operators	Sortable
id	$eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $exists	Sortable
eventId	$eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $exists	Sortable
name	$eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $exists	Sortable
description	$eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $exists	Sortable
limit	$eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $exists	Sortable
pricing_method.pricing_type	$eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $exists	Sortable
feeType	$eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $exists	Sortable
saleStatus	$eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $exists	Sortable
updatedDate	$eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $exists	Sortable
createdDate	$eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $exists	Sortable
hidden	$eq, $ne, $in, $nin, $exists	Sortable
pricing_method.free	$eq, $ne, $in, $nin, $exists	Sortable

Related content: API Query Language, Ticket Definitions Query endpoint

Ticket Definitions v3: Sample Use Cases & Flows

This article presents possible use cases and corresponding sample flows that your app can support. It provides a useful starting point as you plan your app's implementation.

Add a specific-price ticket counter for an event

This use case demonstrates how you can update your event site with a ticket counter for specific-price tickets. This counter provides real-time information on the availability of tickets for customers to see. For example, your page can have a counter that says "Only 3 tickets left for this price." By displaying the number of tickets remaining, you can motivate customers to buy tickets promptly.

To create a ticket counter, follow these steps:

1. Call Get Ticket Definition and retrieve either:

• The salesDetails.unsoldCount and fixedPrice.value values (for fixedPrice pricing method).
• The salesDetails.unsoldCount and pricingOptions.optionDetails.price.value field values (for optionalPrice pricing method).

1. Pass these retrieved values in your app to initialize the counter on your website, displaying the number of available tickets at the specified price.

2. On an ongoing basis, listen for each new ticket purchase using the Order Confirmed Webhook.

3. When the webhook is triggered, you'll receive an order in the payload. Retrieve the ticketDefinitionId value from the event data.

4. Send the extracted ticketDefinitionId value to your site and compare it with the ticket definition ID for which the counter is set. If they match, call Get Ticket Definition again to retrieve the updated salesDetails.unsoldCount value. Send this new decreased value to your website to update the ticket counter.

Sync ticket definitions with an external ticketing system

If you're using a Wix site to manage events and another system to handle ticketing, you can synchronize ticket definitions between them whenever a definition is updated on the site. This includes aspects such as ticket types, pricing, availability, and any other relevant ticket settings. This synchronization eliminates the need for manual updates and reduces the risk of discrepancies between systems.

To upload and update all ticket definitions defined on the Wix site to your external system for the first time, follow these flows:

• Initial setup
• Synchronize to the external system

Part 1: Initial setup

1. Create a custom field in your system that stores the ticket definition ID for a particular event to ensure a 1-to-1 relationship with the external ticketing system. Craft your code so that this ID won't be overwritten by future updates from your app.

2. Create a mapping from the site ticket definition fields to the system fields that will be used whenever site ticket definitions and the external system are synchronized.

3. Query Ticket Definitions by eventId and send the relevant information to the external ticketing system.

Part 2: Synchronize to the external system

1. On an ongoing basis, listen for changes to site ticket definitions with these webhooks:

   • Ticket Definition Created Webhook
   • Ticket Definition Updated Webhook
   • Ticket Definition Deleted Webhook

2. When one of the above webhooks is triggered, you'll receive the ticket definition in the payload. You can bring those changes to the ticketing system by retrieving the relevant info from the payload, and use mapping to take action on the external system:

   • For created and updated ticket definitions retrieve the relevant info from the createdEvent.currentEntity object.

   • For deleted ticket definitions retrieve the createdEvent.currentEntity.id value.

Notify customers when tickets go on sale

Let customers know when ticket sales for an event begin. You can send automated notifications to customers with email or push notifications. These notifications make customers aware of ticket availability so they can secure their tickets promptly.

To send notifications about the start of ticket sales, follow these steps:

1. Get Ticket Definition.

2. Retrieve the salePeriod.startDate field value, and write your code so that the value can be passed to your marketing tool.

3. Request and filter the list of subscribers in your external marketing tool based on customers subscription status for the current event.

4. When the ticket sale start date arrives, send notifications to your customers who have opted in to receive marketing emails.