Availability and Pricing Endpoints

Spektrix doesn't store availability or prices. It reads them from your connector whenever it needs them, so these endpoints should return up-to-date data from the source system.

Prices are returned per price band and ticket type. Each amount is the full price the agent pays the source system for one ticket, including any fees, in the source system's currency. That currency must match the Spektrix client's currency.

Get instance summaries

GET instances/status?ids={instanceIds}

Returns the headline availability and prices of several instances at once. Spektrix uses this for event lists and calendars, where it needs a quick summary of many instances.

Query parameter	Required	Description
`ids`	Yes	Comma-separated instance ids.

Response: 200 OK

[
  {
    "instanceId": "2AEBCDFG",
    "available": 230,
    "pricesByBand": [
      {
        "priceBandId": "7AEBCDFG",
        "prices": [
          { "isDefault": true, "amount": 35.00, "ticketTypeId": "5AEBCDFG" },
          { "isDefault": false, "amount": 28.00, "ticketTypeId": "6AEBCDFG" }
        ]
      }
    ]
  }
]

Field	Type	Description
`instanceId`	string	The instance this summary is for. Return one entry for each requested instance.
`available`	integer	The number of tickets the agent can still buy across the whole instance, reserved and unreserved.
`pricesByBand`	array	For each price band on sale, a price for each ticket type. See prices.

Prices

pricesByBand has the same shape in both availability endpoints:

Field	Type	Description
`priceBandId`	string	The price band.
`prices[].ticketTypeId`	string	The ticket type this price is for.
`prices[].amount`	number	The full price for one ticket.
`prices[].isDefault`	boolean	`true` for the ticket type offered first in this band. Spektrix also shows this price where it needs a single price for the band. Mark one price in each band as the default.

Get instance status

GET instances/{instanceId}/status

Returns the live, seat-by-seat availability and prices of a single instance. Spektrix calls this when it shows a seating plan and while adding seats to a basket.

Response: 200 OK

{
  "pricesByBand": [
    {
      "priceBandId": "7AEBCDFG",
      "prices": [
        { "isDefault": true, "amount": 35.00, "ticketTypeId": "5AEBCDFG" }
      ]
    },
    {
      "priceBandId": "8AEBCDFG",
      "prices": [
        { "isDefault": true, "amount": 20.00, "ticketTypeId": "5AEBCDFG" }
      ]
    }
  ],
  "availableSeats": [
    { "priceBandId": "7AEBCDFG", "seatIds": [ "11AEBCDF", "12AEBCDF", "16AEBCDF" ] }
  ],
  "allocatedSeats": [
    {
      "allocationId": "15AEBCDF",
      "allocationName": "Press hold",
      "seatIds": [ "16AEBCDF" ]
    }
  ],
  "unavailableSeats": [ "14AEBCDF" ],
  "seatInformation": [
    { "label": "Restricted view", "seatIds": [ "12AEBCDF" ] }
  ],
  "areas": [
    {
      "areaId": "25AEBCDF",
      "available": 120,
      "capacity": 150,
      "priceBandIds": [ "8AEBCDFG" ]
    }
  ]
}

The response has three parts: prices, which apply to the whole instance, then reserved seats and unreserved areas.

Instance prices

Field	Type	Description
`pricesByBand`	array	The prices of every band on sale in the instance. It covers both reserved seats and unreserved areas. See prices.

Reserved seats

Reserved seats are reported for the whole instance, not area by area. Seat ids are unique across the plan, so Spektrix already knows which area each seat belongs to from the seating plan.

Every seat the agent can see must appear in exactly one of these lists:

List	Meaning
`availableSeats`	Seats the agent can buy, grouped by price band. This includes allocated seats the agent may sell.
`unavailableSeats`	Seats the agent can't buy because they're sold, reserved, in another basket or held for someone else. Include seats that are already in this agent's own basket.

A seat that's in neither list is hidden from the plan for this instance. Use this for seats that aren't on sale at all for the instance.

Field	Type	Description
`availableSeats[].priceBandId`	string	The price band of these seats.
`availableSeats[].seatIds`	string[]	Available seats in this band.
`allocatedSeats[].allocationId`	string	Your id for a named allocation, or hold, that some available seats belong to.
`allocatedSeats[].allocationName`	string	The allocation's name. Staff see it when mapping the allocation to a Spektrix lock type. This field will be removed in a future version: see the note below.
`allocatedSeats[].seatIds`	string[]	Seats from `availableSeats` that are in this allocation.
`unavailableSeats`	string[]	Seats the agent can't buy.
`seatInformation`	array	Optional. Labels shown against seats, regardless of whether they're available. Leave it out, or return an empty list, if there are none.
`seatInformation[].label`	string	Required for each entry. The label to show, such as `Restricted view`.
`seatInformation[].seatIds`	string[]	The seats the label applies to.

Allocations

allocatedSeats lets the source system hold back seats for particular purposes, such as press seats or wheelchair spaces. Staff map each allocation to a Spektrix lock type, which controls how the seats are displayed and who can sell them. Seats in an allocation that hasn't been mapped aren't offered for sale.

Upcoming change: allocationName

A future version of Spektrix Connect will add a catalogue endpoint that lists every allocation type, with its id and name. Spektrix will then get allocation names from that endpoint, and allocationName will be removed from this response. Keep returning allocationName for now. When the new endpoint is available, you'll need to implement it, and allocatedSeats will only need allocationId and seatIds.

Unreserved areas

Unreserved areas have no seats, so their availability is reported as a count. Include an entry in areas for every Unreserved area in the plan. You can include entries for reserved areas, but Spektrix ignores them.

Field	Type	Description
`areas[].areaId`	string	The area's id from the seating plan.
`areas[].available`	integer	The number of tickets the agent can still buy in the area.
`areas[].capacity`	integer	The area's total capacity.
`areas[].priceBandIds`	string[]	The price band the area's tickets are priced from. An unreserved area has one band.

Get instance summaries​

Prices​

Get instance status​

Instance prices​

Reserved seats​

Unreserved areas​