Adding Items to the Basket
In the following article, links will be referenced as originating from system.spektrix.com. If you have implemented a custom domain for your Integration, please replace system.spektrix.com with your chosen subdomain.
Using the Spektrix API, it’s possible to add tickets for multiple events or instances, as well as other items such as donations or merchandise, to an online basket with one action.
There are many example uses, such as booking for classes, courses and festivals, or meal/drink bundles including an event ticket and a meal/drink voucher.
If you are planning on building your own seat selector, please contact support first.
Below we have given examples of using our API of how you can extract the information you need. If you would like to look through the full Endpoint list to see everything available to you inclusing all URI parameters please navigate here
The Basics
All calls below can be performed without any Authentication.
You’ll need to use the Web User mode of the API. The suggested method outlined below makes use of publicly available information requiring no authentication, and only needs to post items to a single basket at a time. Web User mode provides all necessary endpoints for this and requires no authentication.
To ensure that the session is carried over between sending and retrieving basket information, you'll need to explicitly include cookies as part of your call, as they are not included by default in a CORS request. To achieve this, you need to set the XMLHttpRequest’s withCredentials property to true. Here’s how that would look like in JavaScript - XHR.
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://customdomaingoeshere/TheClientName/api/v3/basket");
xhr.send();
You may still get an HTTP 200 response even if you don’t add
withCredentials = true
. However, it is likely that your call will return an empty basket, so make sure you add it.
The full documentation for is here, and the different modes can be selected at the top of the page to filter the contents;
https://system.spektrix.com/apitesting/api/v3/Help
In order to add items to a basket using API v3, a series of GET requests will first need to be made to gather the information required to construct the body of the POST calls. These requests can be made server side, with the responses being cached, or client-side directly from the customer’s browser. As an example, for a POST call to add tickets to a basket, the body of the call may contain details about the instance, seat, seating plan and ticket type, depending on how the event has been set up. The body information can be provided by responses to real-time or cached GET calls.
If the selection is to be made up of different Item Types, e.g. Event Tickets and Merchandise Items, there will need to be multiple POST calls made to the basket, one for each item type. If all items to be added to the basket are the same type, then you can add multiples of the required item within the body of a single call.
Tickets
The information required in a POST call to the v3/basket/tickets
endpoint is the same information that is required when adding tickets to a basket via the Spektrix sales or web interface; the customer would first select their event, then their instance, then the relevant seating plan/area (or seat, if the event has reserved seating), before selecting their ticket type.
Unreserved Seating Plans
The following outlines the steps for an unreserved event with additional details below for Reserved.
The minimum information required when adding tickets for an Event Instance with a single area unreserved seating plan is as follows;
- Instance ID
- Seating Plan ID
- Ticket Type ID
In order to find this information there are a series of GET requests required, as demonstrated by the examples below.
Events
The first step is to find the relevant events, much like searching for events when booking online.
For more details on optional queries for Event and Instances call please look through our guide to Filtering Events
To retrieve all Events that have Instances in the future using today's date;
GET
https://system.spektrix.com/{{clientname}}/api/v3/events?instanceStart_from={{date
in yyyy-mm-dd}}
{
"description": "Event Description",
"htmlDescription": "<div id>\r\n Clients Web Copy \r\n</div>",
"duration": Duration in Minutes,
"imageUrl": "link to image url",
"isOnSale": true,
"name": "Event Name",
"instanceDates": "Date Range of Instances",
"thumbnailUrl": "link to thumbnail image url",
"webEventId": Optional Client ID,
"id": "Event ID",
"firstInstanceDateTime": "YYYY-MM-DDTHH:MM:SS",
"lastInstanceDateTime": "YYYY-MM-DDTHH:MM:SS",
"attribute_Name": "attribute value"
}
When pulling Events we advise only pulling the data required, and recommend running calls in small date batches using the available parameters starting from "today" unless historic event data is required.
Once you have found the required Event IDs via the API, you can use them to find the relevant Instance IDs, as follows.
Instances
An event can have a single or multiple instances in Spektrix. Instances can be recurring, e.g. every Tuesday for a month, or from e.g. Tuesdays to Saturdays over a specified period. Each Instance has a unique Instance ID.
GET
https://system.spektrix.com/{{clientname}}/api/v3/events/{id}/instances?start_from={date
in yyyy-mm-dd}
{
"isOnSale": true,
"planId": "Seating Plan ID",
"priceList": {
"id": "Price List ID"
},
"event": {
"id": "Event ID"
},
"start": "Start Date/Time",
"startUtc": "Start Date/Time in UTC",
"cancelled": True or False,
"id": "Instance ID",
"hasBestAvailableOverlay": true,
}
When pulling Instances we advise only pulling the data required, and recommend running calls in small date batches using the available parameters starting from "today" unless historic instance data is required.
The required for the next steps:
- “Id” - This is the instance ID, which will be used in the body of the POST request to specify the performance that a ticket is being purchased for.
- “planId” - This is the Seating Plan ID, which will also be used in the body of the POST request, this time to specify the area that the ticket is being purchased for. For unreserved seating plans with multiple areas, the value for planID is that of the specific area. You can get the value of area id by making a GET request to
v3/instances/{{instanceID}}/plan
. - “priceList: id” - Making another GET request using the Price List ID will show the available Ticket Types.
Ticket Type
The final piece of information required in order to add tickets to the basket is the Ticket Type ID.
Use a GET call to the following endpoint to return details of the price list for the specified Event Instance;
GET
https://system.spektrix.com/{{clientname}}/api/v3/instances/{{instanceID}}/price-list
{
"id": "price-listidstring",
"prices": [
{
"id": "priceidstring",
"isBandDefault": true,
"amount": 15,
"ticketType": {
"id": "tickettypeidstring",
"name": "Full Price"
},
"priceBand": {
"id": "pricebandidstring",
"name": "Band A"
}
},
{
"id": "priceidstring",
"isBandDefault": false,
"amount": 10,
"ticketType": {
"id": "tickettypeidstring",
"name": "Concession"
},
"priceBand": {
"id": "pricebandidstring",
"name": "Band A"
}
}
]
}
This request will show the details of all available Ticket Types and their prices, along with the Price Band details, for the event instance specified.
The “id” of the desired Ticket Type is the final piece of information required in order to POST tickets to the basket for an Event Instance created with an unreserved, single area seating plan.
To retrieve information on ticket commissions, you can use the special query parameter $expand and expose the sub-resource of customItems. These will only display if the system is set up in a way that itemises commissions to end-customers - more information here on how to display commissions as itemised. Note that changing this setting will not only affect this api endpoint but also iframes and confirmation emails.
GET
https://system.spektrix.com/{{clientname}}/api/v3/instances/{{instanceID}}/price-list?$expand=prices/customItems
{
"id": "price-listidstring",
"prices": [
{
"id": "priceidstring",
"isBandDefault": true,
"amount": 15,
"ticketType": {
"id": "tickettypeidstring",
"name": "Full Price"
},
"priceBand": {
"id": "pricebandidstring",
"name": "Band A"
}
"customItems": [
{
"name": "Commission",
"amount": 1.5,
"displayMode": "IncludedInPriceButDisplayed"
}
],
},
{
"id": "priceidstring",
"isBandDefault": false,
"amount": 10,
"ticketType": {
"id": "tickettypeidstring",
"name": "Concession"
},
"priceBand": {
"id": "pricebandidstring",
"name": "Band A"
}
}
]
}
Checking Availability
It may be necessary to make periodic or real-time calls to determine whether the chosen event instances have current availability.
Use a GET call to the following endpoint to return a summary of the availability for the specified Event Instance;
GET
https://system.spektrix.com/{{clientname}}/api/v3/instances/{{instanceID}}/status?includeChildPlans=true
{
"name": "Example Seating Plan Name",
"available": 1000,
"wheelchairAvailable": 0,
"specialAvailable": 0,
"capacity": 1000,
"inBasket": 0,
"unavailable": 0
}
This call will return a summary of the current Event Instance availability.
The URL query parameter is optional, however, for events built with multi-area seating plans, it will be necessary to append the query ‘?includeChildPlans=true’ to see details for all areas of the plan. It is generally advisable to include this parameter.
Add tickets to the Basket
Once the necessary GET requests have been made, the next step is to POST this information in order to add ticket(s) to the basket.
The POST request should be a client-side request from the user's browser. The Instance ID, Plan ID and Ticket Type ID will need to be included in the body of the request.
https://system.spektrix.com/{{clientname}}/api/v3/basket/tickets
[
{
"instance": "Instance ID",
"seatingPlan": "Seating Plan ID",
"type": "Ticket Type ID"
},
{
"instance": "Instance ID",
"seatingPlan": "Seating Plan ID",
"type": "Ticket Type ID"
}
]
[
{
"band": {
"id": "Band ID"
},
"event": {
"id": "Event ID"
},
"instance": {
"id": "Instance ID"
},
"planId": "Seating Plan ID",
"seatName": "",
"planName": "Unreserved Example",
"type": {
"id": "Ticket Type ID"
},
"ticketType": {
"id": "Ticket Type ID"
},
"ticketType_Comment": "Will be removed in a future API release - Use 'Type' instead",
"delivered": false,
"barcode": null,
"offer": null,
"discount": 0.0,
"price": 10.0,
"total": 10.0,
"id": "Ticket ID"
}
]
Multiple tickets can be purchased by repeating the required body parameters in an array, as per the above example. A use case for this is adding tickets from multiple instances that are all part of the same course/class creating a one-click bundle.
Once a successful POST has been made, a 200 response with details of the basket and all associated tickets will be returned.
You can then decide to send the customer to the designated page on the site containing the basket/cart or consider upselling and promoting other items.
Reserved Seating Plans
The process for adding tickets to the basket for reserved seating plans is similar, however, there are a couple of extra steps required in order to get all of the information.
Retrieve Instance Seat Status
Note that this call will provide seat status for all areas.
This call provides with up to date information to the availability of seats. Seats are shown by ID, in the Price Band given to them and by a specific status identifier.
These are;
- A = Available
- U = Unavailable
- I = Seat information
Making an authorised call to this endpoint will return richer information. For more details see Reserved Seat Status.
https://system.spektrix.com/{{clientname}}/api/v3/instances/{{instanceid}}/status/detail?includeChildPlans=true
A:Price Band ID : 1,2,3,4,5,6,7,8,9,10,11, etc
U:Price Band ID: 18, 19, etc
I:Seat Information : 1,2 etc
Add tickets to the basket
Add tickets to the basket, but now adding the desired seat ID.
https://system.spektrix.com/{{clientname}}/api/v3/basket/tickets
[
{
"instance": "Instance ID",
"seat": "Seat ID",
"type": "Ticket Type ID"
}
]
Best Available
To purchase seats on a reserved plan, you may also use a best available option. Your client you integrate with will be able to tell you if an instance can be sold via best available.
Adding tickets via best available will adhere to the auto-distancing rules set against the instance by the client you are working with.
Add Tickets to Basket
Provide the quantity of tickets required. You can also provide a list of the bands and/or areas that you want to select the seats from. See the help page for further info:
https://system.spektrix.com/{{clientname}}/api/v3/basket/tickets/best-available
{
"instance": "Instance ID",
"quantity": 2
}
Other Items
Although you can use our Web Components alongside the options above, you may wish to add additional, non-ticketing items yourself via the API.
Each item has a corresponding basket endpoint the items must be added to so will be separate calls to the ones above.
Donations
In order to make a donation through Spektrix, the money has to be assigned to a fund.
To POST a donation to the basket, the Json body of the request will need to include the fund ID and the donation amount.
https://system.spektrix.com/{{clientname}}/api/v3/funds
{
"id": "fundId",
"name": "Fund Name",
"description": "",
"code": "",
"defaultDonationAmount": 0.0
}
https://system.spektrix.com/{{clientname}}/api/v3/basket/donations
[
{
"amount": 5.0,
"fundId": "fundId"
}
]
Merchandise
In the API merchandise items are called “stock-items”. To view all available merchandise and then add to the basket, use the following:
https://system.spektrix.com/{{clientname}}/api/v3/stock-items
[
{
"description": "",
"htmlDescription": "",
"imageUrl": "",
"name": "Name of Item",
"postageAndPacking": 0.0,
"price": 0.0,
"stockLevel": 0,
"thumbnailUrl": "",
"id": "itemId"
}
]
https://system.spektrix.com/{{clientname}}/api/v3/basket/merchandise
[
{
"stockItem": "itemId"
}
]
Memberships
To view all the available memberships and then add to the basket, use the following:
https://system.spektrix.com/{{clientname}}/api/v3/memberships
[
{
"description": "",
"htmlDescription": "",
"id": "membershipId",
"imageUrl": "",
"name": "Membership Name",
"thumbnailUrl": "",
"price": 50,
"renewalPrice": 45
}
]
https://system.spektrix.com/{{clientname}}/api/v3/basket/membership-subscriptions
[
{
"membership": "membershipId"
}
]
You can add multiple different memberships by including the relevant ID’s however, you can’t add more than 1 membership of the same type to the basket.
If you’d like to add an auto renew membership you’ll need to include that in the body of the array: "autoRenew": true
Capturing additional information for Tickets and Orders
It is possible to capture additional information for tickets and orders using Attributes, by using the PATCH method.
When PATCHing the attribute it must be written how it is in the Settings Interface, including spaces and correct capitalization, and not how it is returned in the Basket response. The attribute must be set to ‘Visible in API’.
Ticket Attributes
To capture additional information on tickets in the basket, you can use ticket attributes. Once you have added tickets to the basket using the POST method (as outlined above for unreserved seating plans, reserved seating plans, or using the best-available endpoint), you will PATCH the ticket attribute to the tickets, indicating the specific ticket by adding its ticket ID.
https://system.spektrix.com/{{clientname}}/api/v3/basket/tickets/{{ticketid}}
[
{
"attribute_example of Attribute": "Please arrive on time"
}
]
[
{
"band": {
"id": "Band ID"
},
"event": {
"id": "Event ID"
},
"instance": {
"id": "Instance ID"
},
"planId": "Seating Plan ID",
"seatName": "",
"planName": "Unreserved Example",
"type": {
"id": "Ticket Type ID"
},
"ticketType": {
"id": "Ticket Type ID"
},
"ticketType_Comment": "Will be removed in a future API release - Use 'Type' instead",
"delivered": false,
"barcode": null,
"offer": null,
"discount": 0.0,
"price": 10.0,
"total": 10.0,
"id": "Ticket ID",
"attribute_ExampleOfAttribute": "Please arrive on time",
"attribute_GroupLeader": false,
"attribute_ConcessionType": ""
}
]
You can also add the same attribute across all tickets in the basket with PATCH https://system.spektrix.com/{{clientname}}/api/v3/basket/tickets
.
Order Attributes
To capture additional information on the whole order, you can use order attributes. Order attributes can be set up to be visible in the checkout iframe under Additional Details and/or the API so you could collect information via the API that doesn’t appear in the checkout iframe.
Use cases include, but not limited to, capturing access requirements, dietary requirements or name of guest. The information captured sits against the whole order.
You cannot PATCH order attributes to an empty basket. The example below assumes we have already added tickets.
https://system.spektrix.com/{{clientname}}/api/v3/basket
[
{
"Attribute_access requirements": "Best view of captioning"
}
]
{
"totalDiscount": 0.0,
"defaultCardPaymentFee": 0.0,
"promoCode": null,
"id": "basketid",
"basketId": "basketid",
"basketId_Comment": "Will be removed in a future API release - Use 'Id' instead",
"transactionCommission": {
"waived": false,
"amount": 0.0
},
"disableWebComponents": null,
"hash": "NotLoggedIn",
"customPayments": [],
"customer": null,
"merchandiseItems": [],
"donations": [],
"notes": null,
"tickets":
[
{
"band": {
"id": "Band ID"
},
"event": {
"id": "Event ID"
},
"instance": {
"id": "Instance ID"
},
"planId": "Seating Plan ID",
"seatName": "",
"planName": "Unreserved Example",
"type": {
"id": "Ticket Type ID"
},
"ticketType": {
"id": "Ticket Type ID"
},
"ticketType_Comment": "Will be removed in a future API release - Use 'Type' instead",
"delivered": false,
"barcode": null,
"offer": null,
"discount": 0.0,
"price": 10.0,
"total": 10.0,
"id": "Ticket ID",
"attribute_ExampleOfAttribute": "Please arrive on time",
"attribute_GroupLeader": false,
"attribute_ConcessionType": ""
}
],
"membershipSubscriptions": [],
"giftVouchers": [],
"total": 10.00,
"attribute_AccessRequirements": "Best view of captioning",
"attribute_OptOutOfMembershipBenefits": false,
"attribute_VisitSpend": "",
}
Other use cases for Order Attributes are to capture additional information for items in the basket that are not tickets, such as Memberships, Donations, Merchandise. Once you have added an item in the basket using the POST method, you can then PATCH with the order attribute.
https://system.spektrix.com/{{clientname}}/api/v3/basket/donations
[
{
"amount": 10.0,
"fundId": "Fund ID",
"isAnonymous": true
}
]
https://{{custom domain}}/{{clientname}}/api/v3/basket/
[
{
"attribute_Opt Out of Membership Benefits": "1"
}
]
{
"totalDiscount": 0.0,
"defaultCardPaymentFee": 0.0,
"promoCode": null,
"id": "basketid",
"basketId": "basketid",
"basketId_Comment": "Will be removed in a future API release - Use 'Id' instead",
"transactionCommission": {
"waived": false,
"amount": 0.0
},
"disableWebComponents": null,
"hash": "NotLoggedIn",
"customPayments": [],
"customer": null,
"merchandiseItems": [],
"donations": [
{
"amount": 10.00,
"fund": {
"id": "fund ID"
},
"recognitionName": null,
"isAnonymous": false,
"tributeTypeId": null,
"tributeName": null,
"id": "donation ID"
}
],
"notes": null,
"tickets": [],
"membershipSubscriptions": [],
"giftVouchers": [],
"total": 10.00,
"attribute_AccessRequirements": "",
"attribute_OptOutOfMembershipBenefits": true,
"attribute_VisitSpend": "",
}
Returning the Basket
At any point during the above, you can always return the full contents of the users basket by using the following.
https://system.spektrix.com/{{clientname}}/api/v3/basket
Removing Items
SImilar to the calls above, using a DELETE command to the specific basket/item endpoint will allow you to remove a specific ticket, donation etc from the users basket.
All items in a basket have a unique id
that can be used in the below calls. The below all use URI parameters to DELETE and do not require a body to be sent.
https://system.spektrix.com/{{clientname}}/api/v3/basket/tickets?ticketIds=ticketid1,ticketid2
etc
https://system.spektrix.com/{{clientname}}/api/v3/basket/donations?donationIds=donationid1,donationid2
etc
https://system.spektrix.com/{{clientname}}/api/v3/basket/merchandise?merchandiseItemIds=merchandiseItemId1,merchandiseItemId2
etc
https://system.spektrix.com/{{clientname}}/api/v3/basket/membership-subscriptions?subscriptionIds=ticketid1,ticketid2
etc
Clearing the Basket
To fully clear the basket of all contents, an empty body
can be sent to v3/basket/clear.
https://system.spektrix.com/{{clientname}}/api/v3/basket/clear
Things to consider
It’s important to think about how you want your site to behave if there is an error. Although errors could occur for a number of reasons a couple to think about are:
- If 1 instance or item is sold out or not onsale online, but the others are
- There are two courses on the same day with the same name
- A customer is trying to buy a membership they already have before it can be renewed
- Are all customers eligible to purchase all the items