Temporarily hold objects

Rate limits

This endpoint belongs to the priority lane.

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

// No ticket types
$seatsioClient->events->hold(
  "event1", // the event key
  ["A-3", "A-5"], // object labels
  "wvXbB9MlHt" // hold token
);

// Ticket types
$seatsioClient->events->hold(
  "event1",
  [
    ["objectId" => "A-3", "ticketType" => "adult"],
    ["objectId" => "A-5", "ticketType" => "child"]
  ],
  "wvXbB9MlHt" // hold token
);

// No ticket types
await Client.Events.HoldAsync("event1", new [] { "A-3", "A-5" }, "wvXbB9MlHt");

// Ticket types
ObjectProperties object1 = new ObjectProperties("A-3", "adult");
ObjectProperties object2 = new ObjectProperties("A-5", "child");
await Client.Events.HoldAsync("event1", new [] { object1, object2 }, "wvXbB9MlHt");

// No ticket types
client.events.hold("event1", List.of("A-3", "A-5"), "wvXbB9MlHt");

// Ticket types
ObjectProperties object1 = new ObjectProperties("A-3", "adult");
ObjectProperties object2 = new ObjectProperties("A-5", "child");
client.events.hold("event1", List.of(object1, object2), "wvXbB9MlHt");

# No ticket types
client.events.hold("event1", ["A-3", "A-5"], hold_token="wvXbB9MlHt")

# Ticket types
object1 = ObjectProperties("A-3", ticket_type="adult")
object2 = ObjectProperties("A-5", ticket_type="child")
client.events.hold("event1", [object1, object2], hold_token="wvXbB9MlHt")

# No ticket types
client.events.hold('event1', ['A-3', 'A-5'], 'wvXbB9MlHt')

# Ticket types
object1 = {:objectId => 'A-3', :ticketType => 'adult'}
object2 = {:objectId => 'A-5', :ticketType => 'child'}
client.events.hold('event1', [object1, object2], 'wvXbB9MlHt')

// No ticket types
let holdToken = await client.holdTokens.create();
await client.events.hold('eventKey', ['A-3', 'A-5'], holdToken.holdToken);

// Ticket types
let object1 = {objectId: 'A-3', ticketType: 'adult'};
let object2 = {objectId: 'A-5', ticketType: 'child'};
let holdToken = await client.holdTokens.create();
await client.events.hold('eventKey', [object1, object2], holdToken.holdToken);

// No ticket types
holdToken, err := client.HoldTokens.Create()
_, err = client.Events.Hold(event.Key, []string{"A-3", "A-5"}, &holdToken.HoldToken)

// Ticket types
object1 := events.ObjectProperties{ObjectId: "A-3", TicketType: "adult"}
object2 := events.ObjectProperties{ObjectId: "A-5", TicketType: "child"}
holdToken, err := client.HoldTokens.Create()
result, err := client.Events.HoldWithObjectProperties(event.Key, []events.ObjectProperties{object1, object2}, &holdToken.HoldToken)

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"
}

Note

Seats.io differentiates between the technical label and displayed label for a bookable object. Changing the former in an active event can cause problems with existing bookings. Instead change displayed label, which is always safe. To learn more, see understanding labels

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 event groups. Just pass in an array of events instead of a single event.

Response

Without expand=objects 204 - No Content

With expand=objects 200 - ok

{
  "objects": {
    "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"
    }
  }
}

Request​

Response​

Request

Response