A common requirement is to make seats (or GA places) temporarily unavailable for selection, while the ticket buyer finishes the order flow (payment, etc.).

Seats.io supports this out of the box: You can configure your floor plan in such a way that when a user clicks on a seat, his browser will directly tell the seats.io server to temporarily hold the seat for 15 minutes (by default, you can configure this).

This also means that the seat immediately becomes unavailable for other users. To those other users, it will seem as if the seat has been booked.

If the seat is not booked within the 15 minutes it is being held, it will be automatically released. From that moment on, it will be available again for other users to hold and book.

Configure your seating chart

To make the magic happen, you need to supply session: continue to your floor plan configuration. With that option enabled, a new session is started or a previously started session continues. Seats that get selected on will be held automatically for 15 minutes.

However, that's just one part of the puzzle: it’s important that only the user who selected a seat can actually book it later on. For that, you’ll need to use the hold token mechanism.

Hold Tokens

It’s important to make sure that only the person who held the seat can actually book it. To ensure this, the seats.io renderer will generate a hold token and store it in the browser’s session storage. This hold token uniquely identifies the user (or rather: browser) who selected the seat.

To prevent other users from booking that seat, you need to provide the correct hold token when confirming the booking of seats that were temporarily held before: you need to provide it as a parameter to /book, /release and /changeStatus calls for held objects.

The hold token is either available to you either in your client-side code via JavaScript or in a hidden form field.

javascript: use chart.holdToken
hidden form field: supply holdTokenInputName: "holdTokenInput" to your chart config, and if the chart div is wrapped by a <form> tag, Seats will automatically add a hidden form field with the specified name to your form.

Confirming the booking of a seat that was temporarily held

To actually book a seat that’s been held - and so that’s unavailable for anyone else but you -, you need to call the /book endpoint and provide the hold token. Like so:

{
    'objects': ['A-3', 'A-5', 'A-7'],
    'holdToken': 'f5786c28-6f55-11e6-8b77-86f30ca893d3'
}

A 400 (bad request) is returned when one of the objects couldn’t be booked.

Note: It’s perfectly possible to successfully book seats even after the hold has expired, but only if all of the objects are free of course. This may seem counter intuitive, but if you think about it, there is no reason for seats.io to not allow a booking if the seats are free.

An example: suppose that you, as a ticket buyer, temporarily held seat A-1. Then there are two possibilities:

either you /book seat A-1 within the token time frame: your server needs to pass the correct hold token, and you’ll get a 400 bad request if you don’t. That is because seats.io needs to make sure nobody else than you can book the seat.
or you /book seat A-1 after your token expired: the behaviour is as if you didn’t use hold on select at all, meaning:If the seat is still free at that time, the /book call will just go through, with a 200 OK result.If the seat is not free anymore because someone else booked it after your token expired, you’ll get a 400 bad request.

Starting a new

As explained before, the hold token uniquely identifies a ticket buyer. In other words, it’s very much like a session token.

This token is stored in the session storage of the user’s browser, to make sure that the user still has the same seats selected after a page refresh (in case of validation errors in the rest of the registration form, e.g.).

In some cases, however, you may want to explicitly throw away the current hold token (i.e. the session), and have the ticket buyer start over with a new one. To do so, pass in session: 'start' . The floor plan will ignore any previously stored hold tokens, and use a new one.
Any previously selected seats will not be available to the current user anymore: they were auto-hold using the old hold token. But don’t worry, they will get automatically released again when the old token expires.

A typical example of when you want to use session: start is when you have a timer running in your own application. After say 15 minutes, if the booking is not finalized, you’ll do some cleanup and redirect the user to the start of the registration flow. This is where you want to throw away the old hold token and start afresh.
An example of when you don’t want to restart the session, is when the user has selected their seats and filled in some other fields, but forgot to enter their name, a required field in your application. In that case, you’ll want the user to continue with their current seat selection, and so keep using the same hold token. Use session: continue to accomplish that.

Note: if you do use a timer in your app, we recommend to set the seats.io hold period value to just a couple of minutes higher than your own timer. This will ensure tickets won’t get released before your own timer expires.

In Summary

add session: continue to your floor plan configuration.
use session: start whenever you want to reset the user’s seat selection. Previously selected seats will get released automatically after the hold period.
make sure the hold token gets send to your server: either get it via JavaScript (chart.holdToken) or a hidden form field (set the holdTokenInputNameconfig var)
Pass the hold token to the /book, /release and /changeStatus calls you make from your server-side code.

Frequent Questions

Can I change the 15 minutes to another value?
Yes, via your company settings page.

When objects are temporarily held, do I always have to pass the hold token to /book and /changeStatus?
No, you only have to pass the hold token when doing a /book or /changeStatus on behalf of the user that held objects. That way,
seats.io can verify that no other user is trying to claim the same objects.

But in all other cases, you don’t have to pass in the hold token. A good example would be a back office application, in which a venue manager
issues the /changeStatus call. You can safely issue it without passing in the hold token.