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.

After every change, Spektrix reads the whole basket back with get basket. The add, change and remove endpoints don't need to return anything.

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 after every 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.

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 reserved tickets

POST baskets/{basketId}/reserved-tickets

Adds tickets for specific seats to a basket. The body has one entry for each seat. Spektrix reads the new tickets with get basket afterwards, so the response body isn't read.

This request is all-or-nothing. If any requested seat isn't available, add none of them, and return the tickets unavailable error.

Request

[
  {
    "instance": "2AEBCDFG",
    "seat": "11AEBCDF",
    "type": "5AEBCDFG"
  },
  {
    "instance": "2AEBCDFG",
    "seat": "12AEBCDF",
    "type": "6AEBCDFG"
  }
]

Field	Type	Description
instance	string	The instance id.
seat	string	The seat id.
type	string	The ticket type id.

Response: 204 No Content (any 2xx status)

Tickets unavailable

If one or more requested seats are no longer available, return 409 Conflict with this problem details body. List every unavailable seat from the request in data.tickets, using the seat ids Spektrix sent.

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

{
  "type": "https://integrate.spektrix.com/problems/tickets-unavailable",
  "data": {
    "tickets": [
      {
        "seatId": "11AEBCDF"
      },
      {
        "seatId": "12AEBCDF"
      }
    ]
  }
}

Spektrix then tells the customer which seats are no longer available, so they can choose others. Spektrix only recognises this error when both the 409 status and the type URI match.

Add unreserved tickets

POST baskets/{basketId}/unreserved-tickets

Adds tickets for an unreserved area to a basket. Each entry names the area instead of a seat. To add two tickets, Spektrix sends two entries, as in the example below.

This request is also all-or-nothing. If there aren't enough places left for every ticket, add none of them and return an error status.

Request

[
  {
    "instance": "2AEBCDFG",
    "area": "25AEBCDF",
    "type": "5AEBCDFG"
  },
  {
    "instance": "2AEBCDFG",
    "area": "25AEBCDF",
    "type": "6AEBCDFG"
  }
]

Field	Type	Description
instance	string	The instance id.
area	string	The id of an Unreserved area in the seating plan.
type	string	The ticket type id.

Response: 204 No Content (any 2xx status)

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 type. Spektrix reads the new prices with get basket afterwards.

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

Request

{
  "type": "6AEBCDFG"
}

Response: 204 No Content (any 2xx status)

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, and the response body isn't read.

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

Response: 204 No Content (any 2xx status)

Set promo code

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, and Spektrix reads the new prices with get basket.

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: 204 No Content (any 2xx status)

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)