Skip to main content
Seat management covers the operational lifecycle of seats within a Seats.io event: from event creation and short-term holds during checkout, through to final booking confirmation or release on payment failure.
All functions in this section operate against a Seats.io event (identified by event_id), not a chart. A Seats.io event must be created with create_event_seatsio before any hold or booking calls can be made.

​
Full seat reservation flow

1

Create the Seats.io event

Call create_event_seatsio once when setting up a new TMT event to link it to a Seats.io chart. This creates the seat-status tracking layer for that specific event.
2

Hold seats during checkout

When a customer selects seats, call hold_seats_seatsio. This creates a hold token with a 10-minute expiry and immediately reserves the selected seats against that token. Return the hold token to the client.
3

Process payment

While the seats are held, process the customer’s payment through the TMT order and payment system. The hold token keeps the seats unavailable to other buyers.
4

Book seats on success — or release on failure

  • Payment succeeded: call book_seats_seatsio with the event_id, seats, and hold_token. This permanently marks the seats as booked in Seats.io.
  • Payment failed or timed out: call release_seats_seatsio or expire_hold_token_seatsio to free the seats immediately.

​
Create a Seats.io event

create_event_seatsio creates a new event in Seats.io by linking a chart to a TMT event ID. Call this once per TMT event during event setup. 
POST /create_event_seatsio
Content-Type: application/json

{
  "data": {
    "chart_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "event_id": "JAOTIiQrtU1fMWZZY2IZ",
    "name_event": "Festival de Verano 2025",
    "date_event": "2025-07-15"
  }
}

​
Request parameters

​
data.chart_id
string
required
The unique key of the Seats.io chart to use as the venue layout for this event.
​
data.event_id
string
required
The TMT event ID. This becomes the Seats.io event key, linking the two systems.
​
data.name_event
string
required
Display name for the event in the Seats.io dashboard.
​
data.date_event
string
required
Event date in YYYY-MM-DD format.

​
Response fields

​
data.event
object
The Seats.io event object created. Includes id, key (matches the event_id sent), chartKey, name, date, and initial seat status counters.
Success (200) 
{
  "message": "Evento Creado en Seatsio",
  "status": 200,
  "data": {
    "event": {
      "id": 8842,
      "key": "JAOTIiQrtU1fMWZZY2IZ",
      "chartKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Festival de Verano 2025",
      "date": "2025-07-15"
    }
  }
}
The event_id you provide becomes the Seats.io event key. Use this same value in all subsequent hold_seats_seatsio, release_seats_seatsio, and book_seats_seatsio calls.

​
List Seats.io events

list_event_seatsio returns all events in the Seats.io workspace. 
POST /list_event_seatsio
Content-Type: application/json
This function takes no request body.

​
Response fields

​
data.events
array
Array of all Seats.io event objects. Each object includes id, key, chartKey, name, date, and seat status summary fields.
Success (200) 
{
  "message": "Listado de Eventos en Seatsio",
  "status": 200,
  "data": {
    "events": [
      {
        "id": 8842,
        "key": "JAOTIiQrtU1fMWZZY2IZ",
        "chartKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Festival de Verano 2025",
        "date": "2025-07-15"
      }
    ]
  }
}

​
Hold seats

hold_seats_seatsio temporarily reserves a set of seats for a customer. It creates a new hold token with a 10-minute expiry and immediately holds the specified seats against that token. 
POST /hold_seats_seatsio
Content-Type: application/json

{
  "data": {
    "event_id": "JAOTIiQrtU1fMWZZY2IZ",
    "seats": ["A-1", "A-2", "A-3"]
  }
}

​
Request parameters

​
data.event_id
string
required
The Seats.io event key (equal to the TMT event ID used when creating the event).
​
data.seats
array
required
Array of seat labels to hold. Labels must match the object IDs defined in the Seats.io chart (e.g. "A-1", "B-12").

​
Response fields

​
data.hold
object
The hold result returned by Seats.io. Contains details of the hold operation. The hold token object (with token and expiresAt) is embedded within this object and should be stored by the caller for use in subsequent book_seats_seatsio or release_seats_seatsio calls.
Success (200) 
{
  "message": "Asientos reservados correctamente",
  "status": 200,
  "data": {
    "hold": {
      "holdToken": {
        "token": "wvXbB9MlHiudZnPDvNZs",
        "expiresAt": "2025-07-10T14:32:00Z",
        "expiresInSeconds": 600
      }
    }
  }
}
The hold token expires in 10 minutes. If payment is not completed and book_seats_seatsio is not called within that window, the seats are automatically released by Seats.io when the token expires.

​
Release seats

release_seats_seatsio releases held seats back to available status. Call this when a customer abandons checkout or payment fails. 
POST /release_seats_seatsio
Content-Type: application/json

{
  "data": {
    "event_id": "JAOTIiQrtU1fMWZZY2IZ",
    "seats": ["A-1", "A-2", "A-3"],
    "hold_token": "wvXbB9MlHiudZnPDvNZs"
  }
}

​
Request parameters

​
data.event_id
string
required
The Seats.io event key.
​
data.seats
array
required
Array of seat labels to release.
​
data.hold_token
string
The hold token string associated with the hold. If provided, only seats held under this token are released. If omitted, the seats are released regardless of hold token (admin override).

​
Response fields

​
data.release
object
The release result returned by Seats.io.
Success (200) 
{
  "message": "Asientos liberados correctamente",
  "status": 200,
  "data": {
    "release": {}
  }
}

​
Expire a hold token

expire_hold_token_seatsio immediately expires a hold token, releasing all seats associated with it in a single operation. Use this as a cleanup call when an entire checkout session is abandoned. 
POST /expire_hold_token_seatsio
Content-Type: application/json

{
  "data": {
    "hold_token": {
      "token": "wvXbB9MlHiudZnPDvNZs"
    }
  }
}

​
Request parameters

​
data.hold_token
object
required
The hold token object. Must contain a token string property with the hold token value.
​
data.hold_token.token
string
required
The hold token string value. This is extracted as hold_token.token internally and passed to holdTokens.expiresInMinutes with a value of 0 to force immediate expiry.

​
Response fields

​
data.hold_token
object
The hold token object as provided in the request.
​
data.expired
boolean
Always true on a successful response, confirming the token has been expired.
Success (200) 
{
  "message": "Hold token expirado correctamente. Todos los asientos han sido liberados.",
  "status": 200,
  "data": {
    "hold_token": {
      "token": "wvXbB9MlHiudZnPDvNZs"
    },
    "expired": true
  }
}
Prefer expire_hold_token_seatsio over calling release_seats_seatsio for each seat individually when discarding an entire checkout. It releases all held seats in one API call.

​
Book seats

book_seats_seatsio confirms the booking of held seats, marking them as permanently booked in Seats.io. Supports both individually assigned seats and general admission (GA) areas in a single call. 
POST /book_seats_seatsio
Content-Type: application/json
For assigned seats only: 
{
  "data": {
    "event_id": "JAOTIiQrtU1fMWZZY2IZ",
    "seats": ["A-1", "A-2", "A-3"],
    "hold_token": {
      "token": "wvXbB9MlHiudZnPDvNZs"
    }
  }
}
For GA area seats only: 
{
  "data": {
    "event_id": "JAOTIiQrtU1fMWZZY2IZ",
    "seats": [
      { "objectId": "GA-Floor", "quantity": 4 }
    ],
    "hold_token": {
      "token": "wvXbB9MlHiudZnPDvNZs"
    }
  }
}
For a mixed order (assigned + GA): 
{
  "data": {
    "event_id": "JAOTIiQrtU1fMWZZY2IZ",
    "seats": [
      "VIP-1",
      "VIP-2",
      { "objectId": "GA-Floor", "quantity": 2 }
    ],
    "hold_token": {
      "token": "wvXbB9MlHiudZnPDvNZs"
    }
  }
}

​
Request parameters

​
data.event_id
string
required
The Seats.io event key.
​
data.seats
array
required
Array of seats to book. Two element types are supported and can be mixed:
  • Assigned seat — a plain string with the seat label (e.g. "A-1")
  • GA area — an object with objectId (string) and quantity (number)
​
data.hold_token
object
required
The hold token object returned by hold_seats_seatsio. Must contain a token string property.
​
data.hold_token.token
string
required
The hold token string value used to identify the existing hold.

​
Response fields

​
data.booked
object
Results broken out by seat type.
​
data.booked.normalSeatsBooked
object | null
The booking result from Seats.io for assigned (non-GA) seats. null if no assigned seats were in the request.
​
data.booked.gaSeatsBooked
array
Array of GA booking results. Each entry contains objectId, quantity, and the raw Seats.io result for that GA area. Empty array if no GA seats were in the request.
​
data.event_id
string
The event ID from the request, echoed back in the response.
​
data.hold_token
object
The hold token object from the request, echoed back in the response.
​
data.summary
object
A count breakdown of booked seats.
​
data.summary.normalSeats
number
Count of individually assigned seats booked.
​
data.summary.gaSeats
number
Count of GA area entries (not total GA tickets) booked.
​
data.summary.total
number
Total number of entries in the seats array (assigned + GA entries combined).
Success (200) 
{
  "message": "Asientos confirmados correctamente",
  "status": 200,
  "data": {
    "booked": {
      "normalSeatsBooked": {
        "objects": {
          "VIP-1": { "label": "VIP-1", "status": "booked" },
          "VIP-2": { "label": "VIP-2", "status": "booked" }
        }
      },
      "gaSeatsBooked": [
        {
          "objectId": "GA-Floor",
          "quantity": 2,
          "result": {}
        }
      ]
    },
    "event_id": "JAOTIiQrtU1fMWZZY2IZ",
    "hold_token": {
      "token": "wvXbB9MlHiudZnPDvNZs"
    },
    "summary": {
      "normalSeats": 2,
      "gaSeats": 1,
      "total": 3
    }
  }
}
After a successful book_seats_seatsio call, generate the corresponding TMT tickets using tickets_generate and create the order record. Seats.io and TMT ticket state are not automatically synchronised — the booking step in Seats.io must be followed by ticket generation in TMT to complete the sale.

Build docs developers (and LLMs) love

Get started for freeTalk to us