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.
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.
There are two actions types available for interacting with events;
updateEvent, both of which require an
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.
newEventwill 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
updateEventwill 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
updateEventaction allows you to update the metadata stored on-chain for this event.
Event actions are unbilled and will not charge your account.
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:
soldTicketwill create an NFT ticket within the event contract created as part of
resoldTicketwill log a secondary sale event on the ticket.
scannedTicketwill 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.
checkedInTicketis 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.
invalidatedTicketwill 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:
updateTicketwill change the NFT Content URI, which is the media file used on NFT marketplaces and wallets.
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:
soldTicketto create the NFT.
checkedInTicketto finalise the lifecycle.
claimedTicketto 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.
Requested Action Type
- 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.