Basket Endpoints

When a customer or staff member adds a ticket for an imported event to a Spektrix basket, Spektrix holds the ticket in a matching basket in the source system, through your connector. Each Spektrix basket has at most one basket in each source system. Spektrix creates it when the first ticket from that source system is added.

Every endpoint that changes a basket's tickets or their prices (add tickets, change ticket types, remove tickets and set promo code) responds with the whole basket after the change, in the same shape as get basket. Spektrix uses that response instead of reading the basket again, so it only calls get basket when nothing has returned the basket since its last change.

Create basket

POST baskets

Creates an empty basket. The request body is an empty JSON object. Spektrix only reads id from the response.

The agent confirms the basket and delivers the tickets to the customer, so set the basket up in whatever way the source system needs for an agent sale.

Request

{}

Response: 200 OK or 201 Created

{
  "id": "20AEBCDF"
}

Get basket

GET baskets/{basketId}

Returns a basket and every ticket in it, with each ticket's current price. Spektrix calls this when it needs the basket and nothing has returned it since its last change. Changes can reprice other tickets in the basket, for example when an offer applies, so Spektrix updates the price of every ticket from this response.

The endpoints that change a basket return this same response.

Response: 200 OK

{
  "id": "20AEBCDF",
  "tickets": [
    {
      "id": "21AEBCDF",
      "instanceId": "2AEBCDFG",
      "areaId": "10AEBCDF",
      "seatId": "11AEBCDF",
      "priceBandId": "7AEBCDFG",
      "ticketTypeId": "5AEBCDFG",
      "total": 35.00
    },
    {
      "id": "22AEBCDF",
      "instanceId": "2AEBCDFG",
      "areaId": "10AEBCDF",
      "seatId": "12AEBCDF",
      "priceBandId": "7AEBCDFG",
      "ticketTypeId": "6AEBCDFG",
      "total": 28.00
    },
    {
      "id": "23AEBCDF",
      "instanceId": "2AEBCDFG",
      "areaId": "25AEBCDF",
      "seatId": null,
      "priceBandId": "8AEBCDFG",
      "ticketTypeId": "5AEBCDFG",
      "total": 20.00
    }
  ]
}

Field	Type	Description
`id`	string	The basket id.
`tickets[].id`	string	Your id for the ticket. Spektrix uses it to change, remove and confirm the ticket.
`tickets[].instanceId`	string	The instance the ticket is for.
`tickets[].areaId`	string	The area the ticket is in. For an unreserved ticket, this is the area it was added to.
`tickets[].seatId`	string or null	The seat. Leave it out, or set it to `null`, for unreserved tickets.
`tickets[].priceBandId`	string	The ticket's price band.
`tickets[].ticketTypeId`	string	The ticket's ticket type.
`tickets[].total`	number	What the source system charges the agent for this ticket now, including any discounts and fees.

Add tickets

POST baskets/{basketId}/tickets

Adds tickets to a basket. The body has one entry for each ticket. Each entry names its instance and ticketType, and its type says what kind of ticket it is:

Reserved: a ticket for a specific seat.
Unreserved: a ticket for an unreserved area. To add two tickets for the same area, Spektrix sends two entries.

A single request can mix reserved and unreserved tickets across any number of instances and areas. For example, a customer adding seats for one instance and standing tickets for another can be sent as one request. Reject an entry that has both a seat and an area, or neither.

This request is all-or-nothing across the whole request. If any requested ticket can't be added, add none of them and fail the request. If the reason is that seats are no longer available, or an unreserved area doesn't have enough places left, return the tickets unavailable error.

Request

[
  {
    "instance": "2AEBCDFG",
    "seat": "11AEBCDF",
    "ticketType": "5AEBCDFG",
    "type": "Reserved"
  },
  {
    "instance": "2AEBCDFG",
    "seat": "12AEBCDF",
    "ticketType": "6AEBCDFG",
    "type": "Reserved"
  },
  {
    "instance": "3AEBCDFG",
    "area": "25AEBCDF",
    "ticketType": "5AEBCDFG",
    "type": "Unreserved"
  }
]

Field	Type	Description
`instance`	string	The instance id.
`type`	string	`Reserved` or `Unreserved`.
`seat`	string	The seat id. Sent only for `Reserved` tickets.
`area`	string	The id of an `Unreserved` area in the seating plan. Sent only for `Unreserved` tickets.
`ticketType`	string	The ticket type id.

Response: 200 OK or 201 Created, with the basket after the change, in the same shape as get basket.

Return every ticket in the basket, not just the new ones, because adding tickets can reprice the others. Spektrix finds the new reserved tickets by instance and seat. It finds the new unreserved tickets by looking for ticket ids it doesn't already know for that instance and area, so keep ticket ids stable for as long as a ticket is in the basket.

Tickets unavailable

If one or more requested seats are no longer available, or an unreserved area doesn't have enough places left for the requested tickets, return 409 Conflict with this problem details body. Add none of the requested tickets.

List every unavailable seat and every area without enough places in data.tickets, using the ids Spektrix sent. Each entry has the instanceId and either a seatId or an areaId, never both.

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://integrate.spektrix.com/problems/tickets-unavailable",
  "data": {
    "tickets": [
      {
        "instanceId": "2AEBCDFG",
        "seatId": "11AEBCDF"
      },
      {
        "instanceId": "3AEBCDFG",
        "areaId": "25AEBCDF"
      }
    ]
  }
}

Field	Type	Description
`data.tickets[].instanceId`	string	The instance id from the request.
`data.tickets[].seatId`	string	An unavailable seat from the request.
`data.tickets[].areaId`	string	An unreserved area from the request that doesn't have enough places left.

Spektrix then tells the customer which seats, or which areas, are no longer available, so they can choose others. Spektrix only recognises this error when both the 409 status and the type URI match, and every entry in data.tickets is valid. Otherwise it shows a general error.

Change ticket types

PATCH baskets/{basketId}/tickets?ticketIds={ticketIds}

Changes the ticket type of one or more tickets that are already in a basket, for example from Adult to Concession. Every listed ticket takes the new ticketType. The change can reprice other tickets in the basket, so return the whole basket.

Query parameter	Required	Description
`ticketIds`	Yes	Comma-separated ticket ids, for example `21AEBCDF,22AEBCDF`.

Request

{
  "ticketType": "6AEBCDFG"
}

Field	Type	Description
`ticketType`	string	The id of the new ticket type.

Response: 200 OK, with the basket after the change, in the same shape as get basket. Return every ticket in the basket, not just the changed ones.

Remove tickets

DELETE baskets/{basketId}/tickets?ticketIds={ticketIds}

Removes one or more tickets from a basket and releases their seats or places in the source system. The request has no body.

Query parameter	Required	Description
`ticketIds`	Yes	Comma-separated ticket ids, for example `21AEBCDF,22AEBCDF`.

Response: 200 OK, with the basket after the change, in the same shape as get basket. Return every ticket in the basket, not just the remaining ones.

PATCH baskets/{basketId}/promo-code

Applies a promotional code to a basket, or clears it. An empty string clears any code already applied. Applying a code may reprice tickets, so return the whole basket with the new prices.

If the source system rejects the code, fail the request with an error status. Don't ignore the code silently, because Spektrix uses the failure to tell the customer the code wasn't accepted.

Request

{
  "promoCode": "EARLYBIRD"
}

Response: 200 OK, with the basket after the change, in the same shape as get basket.

Set agent customer

PATCH baskets/{basketId}/agent-customer

Records the customer the agent is selling to, and the agent's own order reference, against the basket. This lets the source system attribute the sale and helps its venue staff find the booking on the night.

Spektrix calls this just before it confirms the basket. Any field the agent doesn't have is sent as an empty string. Spektrix still confirms the basket if this request fails, but you should store these details whenever you can.

Request

{
  "agentCustomer": {
    "firstName": "Alex",
    "lastName": "Okafor",
    "addressLine": "12 Example Street, London, EX1 2MP",
    "agentOrderReference": "AG-100234"
  }
}

Field	Type	Description
`agentCustomer.firstName`	string	The customer's first name.
`agentCustomer.lastName`	string	The customer's last name.
`agentCustomer.addressLine`	string	The customer's address, as a single line.
`agentCustomer.agentOrderReference`	string	The Spektrix order reference for this sale.

Response: 204 No Content (any 2xx status)

Create basket​

Get basket​

Add tickets​

Tickets unavailable​

Change ticket types​

Remove tickets​

Set promo code​

Set agent customer​

Create basket

Get basket

Add tickets

Tickets unavailable

Change ticket types

Remove tickets

Set promo code

Set agent customer