Temporarily hold objects

Objects can be held for a certain time period. During this period, other users cannot hold or book the same seats.

By default the expiration time for held objects is 15 minutes, but this can be changed via your company settings page.

Note

You only need this API call when holding best available objects.

If you render the chart with a session parameter, objects get held when the ticket buyer clicks on them. So no need to manually call /hold in that case.

To hold objects using the manual API method, you first need to generate a hold token, which you then pass to the following API call:

POST https://api-{region}.seatsio.net/events/{eventKey}/actions/hold
POST https://api-{region}.seatsio.net/events/{eventKey}/actions/hold?expand=objects

Request#

// No ticket types
{
"objects": ["A-3", "A-5"],
"holdToken": "wvXbB9MlHt"
}
// Ticket types
{
"objects": [
{"objectId": "A-3", "ticketType": "adult"},
{"objectId": "A-5", "ticketType": "child"}
],
"holdToken": "wvXbB9MlHt"
}
// Best available
{
"bestAvailable": {
number: 2,
categories: ["balcony", "stalls"],
extraData: [{"userId": "123"}, {"userId": "456"}],
ticketTypes: ["adult", "child"]
},
"holdToken": "wvXbB9MlHt"
}

After invoking this API call, the objects get the status reservedByToken. (Note: this is a legacy status name: in the past, holding an object was known as reserving an object. We kept the status reservedByToken to maintain backwards compatibility, i.e. to not break existing integrations)

When you're ready to confirm the booking for a held object (e.g. after payment was received), issue a /book or /change-object-status call, passing in the same hold token that was used for acquiring the hold.

If no definitive booking is made before the hold expires, the seat are released again. And if you want to cancel a hold before the hold period expires, you just release the objects.

Even for objects that are held, the hold token is an optional argument to /book and /change-object-status. You only need to pass it when it is the person that made the hold who triggers the API call. If on the other hand you implemented some back office functionality in which venue managers can change the status of held objects, you don't need to pass in the hold token.

info

Holding also works for season tickets. Just pass in an array of events instead of a single event.

Response#

Without expand=objects 204 - No Content

With expand=objects 200 - ok

{
"A-3": {
"label": "A-3",
"labels": {
"own": {
"label": "3",
"type": "seat"
},
"parent": {
"label": "Row A",
"type": "row"
},
},
"ids": {
"own": "3",
"parent": "A"
},
"status": "reservedByToken",
"holdToken": "wvXbB9MlHt",
"categoryLabel": "Ground Floor",
"categoryKey": "4",
"ticketType": "adult",
"orderId": "order1",
"forSale": true,
"objectType": "seat",
"leftNeighbour": "A-2",
"rightNeighbour": "A-4",
"entrance": "Blue"
},
"A-5": {
"label": "A-5",
"labels": {
"own": {
"label": "5",
"type": "seat"
},
"parent": {
"label": "Row A",
"type": "row"
},
},
"ids": {
"own": "5",
"parent": "A"
},
"status": "reservedByToken",
"holdToken": "wvXbB9MlHt",
"categoryLabel": "Ground Floor",
"categoryKey": "4",
"ticketType": "adult",
"orderId": "order1",
"forSale": true,
"objectType": "seat",
"leftNeighbour": "A-4",
"rightNeighbour": "A-6",
"entrance": "Blue"
}
}