Seat Status and Availability

The Spektrix API can retrieve availability status for event instances and events. For details on making queries for Events and Instances you can look through our guide to Filtering Events.

Availability is linked to instances and not whole events, so in order to determine the status of individual events you will need to evaluate the status of each instance. The event-level availability endpoint provides a convenient summary across all instances of an event. Note that the resource isOnSale which is revealed from GET api/v3/events does not represent availability.

note

Making a large number of client-side API requests at once can negatively impact the performance of your website. Calls related to overall Event and Instance availability should generally be cached and made server-side to avoid browser slow-down and rate limiting.

Locks

This guide on status and availability refers to ‘locks’. Spektrix allows clients to ‘lock’ certain seats on a seating plan in order to provide additional information about a given seat or to hold them back from general sale online.

Potential use cases for locks include:

Seats for a personal assistant for a customer who requires 1-1 support, with no customer eligibility criteria. The seats are available to anyone, but hold additional information.
Exclusive seats held back, with a customer eligibility criteria specific to members, while the seats remain unavailable to the general public.
‘House seats’ which are held back and sold at the discretion of the Box Office Manager or released last minute (no longer locked) if not needed.

What this potentially results in is two separate sets of locked seats:

Locked seats that are accessible for the general public that will not change customer-to-customer. Generally, cached server-side calls should be used to access this information.
Locked seats that will change based on whether or not a customer has logged into their account. These locks are customer-specific and can be viewed by making client-side API calls using the custom domain instead of system.spektrix.com. In order to view the set of locked seats that are available to the specific customer requires successful authentication. Customers can log in via the loginlogout.aspx iframe or a client-side API call to v3/customer/authenticate, using the custom domain instead of system.spektrix.com in order to share the session.

Event-Level Availability

Get a summary of availability across all instances of an event within an optional date range. This is useful for displaying overall event status or to display instance status in a calendar / instance list without querying each instance individually.

Request

GET
https://system.spektrix.com/{{clientname}}/api/v3/events/{id}/availability

Parameters

Parameter	Type	Mode	Description
`id`	string	Web, Agent & System Owner	Event API ID (required)
`start_from`	datetime	Web, Agent & System Owner	Optional. Filter instances starting on or after this date. YYYY-MM-DD format.
`start_to`	datetime	Web, Agent & System Owner	Optional. Filter instances starting on or before this date. YYYY-MM-DD format. Must be >= `start_from`.
`customerId`	string	System Owner only	Optional. Calculate each instance's start-selling time for the specified customer. Mutually exclusive with `basketId`.
`basketId`	string	System Owner & Agent	Optional. Calculate each instance's start-selling time using the basket owner's eligibility and basket context, including qualifying promotion codes. Mutually exclusive with `customerId`.
`price-list`	boolean	Web, Agent & System Owner	Optional. Set to `true` to include ticket types, prices, commissions, and ticket donations for each price band. Defaults to `false`.

Response

Each instance includes startSellingForCustomer and startSellingForCustomerUtc. These are the earliest times that the relevant customer can book, taking eligible priority booking periods into account. If no earlier priority booking period applies, the fields contain the instance's general web start-selling time.

If no web start-selling time is configured, both fields are null. This indicates that no start-selling restriction applies and the instance is already available.

In Web mode, the values use the current session's customer and basket context. In Agent mode, pass basketId to use a specific basket's context. In System Owner mode, pass customerId or basketId to calculate customer-specific values; without either parameter, the general web start-selling time is returned.

Web and Agent modes
System Owner Mode

{
  "data": [
    {
      "eventInstanceId": "3603ASVMHKBLJJJMNQJVSSTNNGTBKJMRS",
      "start": "2026-07-15T19:30:00",
      "startUtc": "2026-07-15T18:30:00Z",
      "startSellingForCustomer": "2026-06-15T10:00:00",
      "startSellingForCustomerUtc": "2026-06-15T09:00:00Z",
      "capacity": 500,
      "availability": [
        {
          "priceBand": "2001APNNMRMBJQQPBSCNQGQHGKKCRPSSG",
          "status": "Available",
          "count": 150
        },
        {
          "priceBand": "2001APNNMRMBJQQPBSCNQGQHGKKCRPSSG",
          "status": "Unavailable",
          "count": 350
        }
      ]
    }
  ]
}

{
  "data": [
    {
      "eventInstanceId": "3603ASVMHKBLJJJMNQJVSSTNNGTBKJMRS",
      "start": "2026-07-15T19:30:00",
      "startUtc": "2026-07-15T18:30:00Z",
      "startSellingForCustomer": "2026-06-20T10:00:00",
      "startSellingForCustomerUtc": "2026-06-20T09:00:00Z",
      "capacity": 500,
      "availability": [
        {
          "priceBand": "2001APNNMRMBJQQPBSCNQGQHGKKCRPSSG",
          "status": "Available",
          "count": 100
        },
        {
          "priceBand": "2001APNNMRMBJQQPBSCNQGQHGKKCRPSSG",
          "status": "Unavailable",
          "count": 150
        },
        {
          "priceBand": "2001APNNMRMBJQQPBSCNQGQHGKKCRPSSG",
          "status": "InOtherBasket",
          "count": 25
        },
        {
          "priceBand": "2001APNNMRMBJQQPBSCNQGQHGKKCRPSSG",
          "status": "Reserved",
          "count": 15
        },
        {
          "priceBand": "2001APNNMRMBJQQPBSCNQGQHGKKCRPSSG",
          "status": "Scanned",
          "count": 35
        },
        {
          "priceBand": "2001APNNMRMBJQQPBSCNQGQHGKKCRPSSG",
          "status": "Sold",
          "count": 120
        },
        {
          "priceBand": "2001APNNMRMBJQQPBSCNQGQHGKKCRPSSG",
          "status": "Locked",
          "count": 35
        },
        {
          "priceBand": "2001APNNMRMBJQQPBSCNQGQHGKKCRPSSG",
          "status": "Masked",
          "count": 15
        }
      ]
    }
  ]
}

Field	Description	Web & Agent Modes	System Owner Mode
eventInstanceId	The API ID of the instance	Yes	Yes
start	Instance start time in the client's local timezone (unspecified kind)	Yes	Yes
startUtc	Instance start time in UTC timezone	Yes	Yes
startSellingForCustomer	Earliest time the relevant customer can book, in the client's local timezone. Includes eligible priority booking periods; otherwise returns the general web start-selling time. `null` means no web start-selling time is configured, so the instance is already available.	Yes	Yes
startSellingForCustomerUtc	The same customer-specific start-selling time in UTC, or `null` when no web start-selling time is configured.	Yes	Yes
capacity	Total seats in the instance	Yes	Yes
availability	Array grouped by price band and availability status	Yes	Yes
priceBand	The API ID of the price band	Yes	Yes
status	Availability status of seats in this price band. Web and Agent modes: `Available` (takes into account the customer eligibility to locked seats), `Unavailable`. Owner mode: `Available`, `Unavailable`, `InOtherBasket`, `Reserved`, `Scanned`, `Sold`, `Locked`, `Masked`	Partial	Full
count	Number of seats in this status for this price band	Yes	Yes
ticketTypes	Ticket types and prices for the price band. Only included when `price-list=true`.	Optional	Optional

Including Price Lists

Set price-list=true to add a ticketTypes array to each price-band availability entry:

GET
https://system.spektrix.com/{{clientname}}/api/v3/events/{id}/availability?price-list=true

{
  "priceBand": "2001APNNMRMBJQQPBSCNQGQHGKKCRPSSG",
  "status": "Available",
  "count": 150,
  "ticketTypes": [
    {
      "ticketTypeId": "3001APNNMRMBJQQPBSCNQGQHGKKCRPSSG",
      "isBandDefault": true,
      "amount": 26,
      "customItems": [
        {
          "name": "Commission",
          "amount": 1,
          "displayMode": "IncludedInPriceButDisplayed"
        },
        {
          "name": "Donation",
          "amount": 2,
          "displayMode": "IncludedInPriceButDisplayed"
        }
      ]
    }
  ]
}

amount includes any ticket commission but does not include a ticket donation. customItems identifies the commission and donation amounts separately when applicable.

Error Responses

Status	Scenario	Notes
400	`DateRangeValidationError`	`start_from` is after `start_to`.
400	`BadRequest`	`customerId` and `basketId` are both provided.
403	`Forbidden`	`customerId` is used outside System Owner mode, or `basketId` is used in Web mode.
404	`ResourceNotFound`	Event ID does not exist.

Use Cases

Display overall event availability ("Limited Availability" vs "Sold Out") on event listing pages.
Build event calendars or instances lists with visual availability indicators.

Context Parameters (Owner Mode)

Some System Owner mode endpoints on this page accept optional customerId or basketId query parameters, which simulate what a specific customer or basket owner would see, without needing to authenticate as that customer. These are not a separate API mode — they're optional context parameters layered on top of System Owner mode.

For Event-Level Availability, basketId is also available in Agent mode and is used to calculate startSellingForCustomer from the basket's context.

Parameter	Description
`customerId`	Query availability as if the specified customer were browsing (no active basket). Applies that customer's lock eligibility. Returns a Web-mode response shape.
`basketId`	Query availability as if the basket owner were shopping (includes promo codes and basket context). Returns a Web-mode response shape.

customerId and basketId are mutually exclusive. Both return 403 Forbidden if used in Web mode, and customerId also returns 403 Forbidden in Agent mode.

In the response tables and examples below, calls made with either parameter are labeled "Owner Mode (Context)" to distinguish them from a plain System Owner mode call.

Unreserved Instance Status / Reserved Instance Status Summary

These calls will retrieve the latest seat availability status for instances which can be used for unreserved instances or as a summary of reserved instances when you don't need the status information for each individual seat.

Information returned in the properties specialAvailable and lockInfoSpecialAvailable may differ depending on the logged in customer.

Endpoint	Purpose	Description
`GET v3/instances/{id}/status`	Summary by price band	Returns an overview of the current availability status for an instance
`GET v3/instances/{id}/status/areas/{areaId}`	Single area summary	Returns an overview of the current availability status of a specific area for an instance
`GET v3/instances/{id}/status/areas?areaIds={areaId},{areaId}`	Multiple areas summary	Returns an aggregate overview of the current availability status of a number of specific areas for an instance
`GET v3/instances/{id}/status/areas/all`	Summary of all areas, broken down by area	Returns an overview of the current availability status of every area for an instance, one entry per area

Request

GET
https://system.spektrix.com/{{clientname}}/api/v3/instances/{id}/status?includeLockInformation=true&includeChildPlans=true

Parameters

Parameter	Type	Mode	Description
`includeLockInformation`	string	Web mode & System Owner	`"false"` (default) = no lock data. `"true"` = include lock names and available counts.
`includeChildPlans`	boolean	Web mode & System Owner	Default value is `false`. For events built with multi-area seating plans, it will be necessary to append the query to see details for all areas of the plan. It is generally advisable to include this parameter.
`$expand`	string	Web mode & System Owner	Use `$expand=bands` to see bands with available seats
`customerId`	string	System Owner only	See Context Parameters above. Mutually exclusive with `basketId`.
`basketId`	string	System Owner only	See Context Parameters above. Mutually exclusive with `customerId`.

Response

Web mode
System Owner Mode
Owner Mode (Context)

{
	"name": "Unreserved Example",
	"available": 175,
	"wheelchairAvailable": 0,
	"specialAvailable": 0,
	"capacity": 200,
	"inBasket": 0,
	"unavailable": 25,
	"lockInfoAvailable": [
		{
			"quantity": 3,
			"lockType": {
			"name": "Personal Assistant",
			"id": "601APNNMRMBJQQPBSCNQGQHGKKCRPSSGN"
			}
		}
	],
	"lockInfoSpecialAvailable": [
		{
			"quantity": 2,
			"lockType": {
			"name": "Members Exclusive Seats",
			"id": "1401AHPQBSMRKMCGHQKGHVQVKCQNVNBKN"
			}
		}
	]
}

{
	"name": "Reserved Example",
	"available": 100,
	"wheelchairAvailable": 5,
	"specialAvailable": 10,
	"capacity": 200,
	"inBasket": 3,
	"inOtherBasket": 7,
	"reserved": 4,
	"sold": 45,
	"scanned": 12,
	"lockedUnavailable": 8,
	"masked": 6,
	"lockInfoAvailable": [
		{
			"quantity": 3,
			"lockType": {
			"name": "Personal Assistant",
			"id": "601APNNMRMBJQQPBSCNQGQHGKKCRPSSGN"
			}
		}
	],
	"lockInfoSpecialAvailable": [
		{
			"quantity": 10,
			"lockType": {
			"name": "Members Exclusive Seats",
			"id": "1401AHPQBSMRKMCGHQKGHVQVKCQNVNBKN"
			}
		}
	]
}

{
	"name": "Reserved Example",
	"available": 175,
	"wheelchairAvailable": 0,
	"specialAvailable": 25,
	"capacity": 200,
	"inBasket": 0,
	"unavailable": 25,
	"lockInfoAvailable": [
		{
			"quantity": 3,
			"lockType": {
			"name": "Personal Assistant",
			"id": "601APNNMRMBJQQPBSCNQGQHGKKCRPSSGN"
			}
		}
	],
	"lockInfoSpecialAvailable": [
		{
			"quantity": 2,
			"lockType": {
			"name": "Members Exclusive Seats",
			"id": "1401AHPQBSMRKMCGHQKGHVQVKCQNVNBKN"
			}
		}
	]
}

Field	Description	Web Mode	System Owner Mode	Owner Mode (Context)
name	Display name of the instance or area	Yes	Yes	Yes
available	Unreserved, purchasable seats (excludes locked seats, baskets, reserved, sold)	Yes	Yes	Yes
wheelchairAvailable	Wheelchair-accessible seats that are available	Yes	Yes	Yes
specialAvailable	Seats marked as "special" with lock eligibility applied	Yes	Yes	Yes
capacity	Total seats	Yes	Yes	Yes
bands	Price band breakdown of availability	Yes	Yes	Yes
inBasket	Seats in the customer's active basket	No	Yes (all baskets)	Yes (specified basket)
inOtherBasket	Seats in other customers' baskets	No	Yes	No
reserved	Seats held by venue or system	No	Yes	No
sold	Purchased and delivered seats	No	Yes	No
scanned	Seats marked as scanned/used	No	Yes	No
lockedUnavailable	Locked seats with no available inventory	No	Yes	No
masked	Seats hidden by venue configuration	No	Yes	No
unavailable	General unavailable state (sold, reserved, masked, in other baskets)	No	No	Yes
lockInformation	All locks on the instance (only if `includeLockInformation=true`)	Web-eligible locks	All locks	Web-eligible locks
lockInfoAvailable	Locks without customer eligibility criteria	Yes (when requested)	Yes (when requested)	Yes (when requested)
lockInfoSpecialAvailable	Locks with customer eligibility criteria	Yes (customer's eligibility)	Yes (all eligibilities)	Yes (customer's eligibility)

Error Responses

Status	Scenario	Notes
400	Both `customerId` and `basketId` provided	Cannot use both parameters simultaneously
403	`customerId` or `basketId` used in Web mode	Forbidden: Context parameters require Owner mode
404	Instance not found	Instance ID does not exist

Use Cases

The information on availability can be used to build conditional booking links to instances that show 'limited availability' and 'sold out' messages, dynamic calendar listings, and other similar use cases. Generally, cached server-side calls should be used to access this information.
The information on locked seats can be used:
- by venues that use locks without eligibility criteria, so instances don’t appear sold out if 'locked' seats (available for purchase) are the only ones available. Generally, cached server-side calls should be used to access this information.
- to display different messaging to logged in customers based on their individual eligibility criteria, for example to indicate additional availability to a logged in Member. In order to view this information in the API, these calls would need to be made client-side and only after the customer has logged in. For optimal performance, you can combine cached server-side calls to display availability for the general public, and client-side calls to display the specific availability for the logged in customer.

Detailed Reserved Seat Status

For reserved seating plans, it is possible to get the status of each individual seat. The response uses a compressed text format for efficiency.

Endpoint	Purpose	Description
`GET v3/instances/{id}/status/detail`	All seats with individual status codes	Returns status for every seat in the instance
`GET v3/instances/{id}/status/areas/{areaId}/detail`	Seats within a specific area	Returns status for seats in a specific area only

Request

GET
https://system.spektrix.com/{{clientname}}/api/v3/instances/{instanceId}/status/detail?includeLockInformation=true&includeChildPlans=true

Parameters

Parameter	Type	Mode	Description
`includeLockInformation`	string	Web mode & System Owner	`"false"` (default) = no lock data. `"true"` = include lock IDs and names. `"truewithicon"` = include lock IDs, names, and icon information.
`includeChildPlans`	boolean	Web mode & System Owner	Default value is `false`. For events built with multi-area seating plans, it will be necessary to append the query to see details for all areas of the plan. It is generally advisable to include this parameter.
`customerId`	string	System Owner only	See Context Parameters above. Mutually exclusive with `basketId`.
`basketId`	string	System Owner only	See Context Parameters above. Mutually exclusive with `customerId`.

Response

The response uses a compressed text format with one line per seat status group:

Without lock information:

seatstatus:pricebandid:seatid,seatid,seatid ...

With includeLockInformation=true:

seatstatus:pricebandid:{lockid:"lock name"}:seatid,seatid,seatid ...

With includeLockInformation=truewithicon:

seatstatus:pricebandid:{lockid:"lock name":"description of icon"}:seatid,seatid,seatid ...

Web mode
System Owner Mode
Owner Mode (Context)

A:12345ABCDEF:33,34,35,36,37,38
A:12345ABCDEF:{56789ASDFGH:"Personal Assistant"}:32
U:12345ABCDEF:23,24,25,26,27,28,29,30
W:31234ABCDEF:11,12,13
X:31234ABCDEF:{345678POIUYTR:"Members Exclusive Seats"}:46,47,48

A:12345ABCDEF:33,34,35,36,37,38
A:12345ABCDEF:{56789ASDFGH:"Personal Assistant"}:32
B:12345ABCDEF:10,20,30
E:12345ABCDEF:40,41,42
R:12345ABCDEF:50,51
SO:12345ABCDEF:60,61,62
SC:12345ABCDEF:70,71
L:12345ABCDEF:{345678POIUYTR:"Members Only"}:80,81
M:12345ABCDEF:90,91,92

A:12345ABCDEF:33,34,35,36,37,38
A:12345ABCDEF:{56789ASDFGH:"Personal Assistant"}:32
U:12345ABCDEF:23,24,25,26,27,28,29,30
W:31234ABCDEF:11,12,13
X:31234ABCDEF:{345678POIUYTR:"Members Exclusive"}:46,47,48

Seat Status Code Reference

Code	Label	Web Mode	System Owner Mode	System Owner Mode (Context)	Agent	Description
A	Available	Yes	Yes	Yes	Yes	Available for purchase (general public or customer-eligible)
B	In Basket	Yes	Yes (all)	Yes (specified)	Yes	Seats in an active basket
U	Unavailable	Yes	Yes	Yes	Yes	Sold, reserved, masked, or in another basket
I	Info Label	Yes	Yes	Yes	Yes	Seats with attached information (e.g., "Restricted View"); appears as separate entry
W	Wheelchair-Locked Available	Yes	No	Yes	Yes	Wheelchair-accessible; available for purchase if eligible
X	Locked Available	Yes	No	Yes	Yes	Restricted by eligibility; available if customer qualifies
E	In Other Basket	No	Yes	No	No	In another customer's active basket
R	Reserved	No	Yes	No	No	Reserved tickets
SO	Sold	No	Yes	No	No	Purchased
SC	Scanned	No	Yes	No	No	Ticket already scanned at entry
L	Locked Unavailable	No	Yes	No	No	Locked with no available inventory
M	Masked	No	Yes	No	No	Hidden by venue configuration

Note on customerId / basketId: When using these Context Parameters, responses use Web-mode seat codes only (A, B, U, W, X). Owner-mode-only codes (E, R, L, M, SC, SO, I) are not returned.

Error Responses

Status	Scenario	Notes
400	Both `customerId` and `basketId` provided	Cannot use both parameters simultaneously
403	`customerId` or `basketId` used in Web mode	Forbidden: Context parameters require Owner mode
404	Instance not found	Instance ID does not exist

Use Cases

Build custom reserved seating selectors or interactive seat maps

Locks​

Event-Level Availability​

Request​

Parameters​

Response​

Including Price Lists​

Error Responses​

Use Cases​

Context Parameters (Owner Mode)​

Unreserved Instance Status / Reserved Instance Status Summary​

Request​

Parameters​

Response​

Error Responses​

Use Cases​

Detailed Reserved Seat Status​

Request​

Parameters​

Response​

Seat Status Code Reference​

Error Responses​

Use Cases​

Locks

Event-Level Availability

Request

Parameters

Response

Including Price Lists

Error Responses

Use Cases

Context Parameters (Owner Mode)

Unreserved Instance Status / Reserved Instance Status Summary

Request

Parameters

Response

Error Responses

Use Cases

Detailed Reserved Seat Status

Request

Parameters

Response

Seat Status Code Reference

Error Responses

Use Cases