Actions

The Ticket Engine API has been designed to accept a stream of actions, where each action is an operation that you wish to carry out on the protocol. Over time we've found that commercial ticketing applications often operate using message queues or event driven architectures and separating these actions into separate endpoints often adds additional overhead when it comes to implementation.

Offering a stream endpoint allows integrators on the protocol to forward mixed batches of action requests to the Ticket Engine API and these will be processed in the order they are received.

Action Types

Before any sold tickets can be registered on the protocol, you must first create an event as an eventId will be required when creating a ticket. The Ticket Engine API handles the ordering of transactions so there is no need to wait until the creation of an event has been confirmed on the blockchain, only that the event has been submitted to the Ticket Engine prior to registering the first sold ticket.

Events

There are two actions types available for interacting with events; newEvent and updateEvent, both of which require an eventId. This eventId is a client-side generated ID and can be a maximum of 255 characters in length.

The event ID must be unique to you but there are no restrictions on the content of this field it is possible to use your own existing event ID from your current ticketing systems as long as this uniqueness constraint is met. This event ID will not be propagated to the blockchain and is only used as a reference ID for Ticket Engine to use for subsequest requests.

• newEvent will queue a transaction to create a new smart contract on the blockchain. This gives each event its own namespaced collection and separate blockchain address that can then be used within explorers, marketplaces, and other NFT tooling. All NFT tickets for that event will belong to the smart contract created using the newEvent action.
• updateEvent will update the event's metadata on-chain. While we encourage customers to use as much transparency as possible when creating an event, the real-world can work differently. Event start and end times may be changed, names and headling acts may change, and the updateEvent action allows you to update the metadata stored on-chain for this event.

Event actions are unbilled and will not charge your account.

Tickets

As mentioned, a newEvent action must first be submitted to the API prior to registering a sold tickets. This can be done within the same request but it is necessary for the eventId to be present in the Ticket Engine prior to ticket processing.

There are a number of ticket actions available to change the state of a ticket on-chain:

• soldTicket will create an NFT ticket within the event contract created as part of newEvent.
• resoldTicket will log a secondary sale event on the ticket.
• scannedTicket will issue a non-finalising scan event on a ticket. A scan can happen an unlimited amount of times and should be used for multi-day or multi-gate events.
• checkedInTicket is a scan event that finalises the state of the ticket. For a single-gated event a check-in event should be used instead of a scan. Upon check-in the NFT is ready to be claimed into a user's wallet.
• invalidatedTicket will also finalise the ticket's lifecycle although this will not enable claiming. To be used for event invalidations & cancellations.

Updating metadata does not affect blockchain storage:

• updateTicket will change the NFT Content URI, which is the media file used on NFT marketplaces and wallets.

Ticket Lifecycle

The Ticket Engine lifecycle attempts to be as flexible as possible so that it can accomodate all customer workflows, although there are some validations that occur between states.

The most basic lifecycle for a sold ticket that is then validated upon entry and then claimed by a user would take the flow:

1. soldTicket to create the NFT.
2. checkedInTicket to finalise the lifecycle.
3. claimedTicket to claim to a user's wallet.

Checked-in and invalidated tickets have already completed their lifecycle and cannot be further scanned or resold. Tickets cannot be resold after the first scan is registered. Claiming is only possible for checked-in tickets.

👍

Recap

• Ticket Engine will handle queuing, no need to wait for blockchain confirmations.
• An event must be submitted to the API before registering the first sold ticket.
• Full schema for each action type can be found within the stream endpoint documentation.
• Event actions are not billed. Sold tickets will be billed upon blockchain confirmation.
• Reselling or scanning is not available for checked-in or invalidated tickets.
• Claiming is only possible for checked-in tickets.