Adding Items to the Basket

Working with custom domains

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.

Custom reserved seat selector

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

tip

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.

Caching

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.

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 of cached GET calls.

Though it is possible to get client-side responses directly from the customer’s browser, making a large number of client-side API requests at once can negatively impact the performance of your website. It should be avoided when possible to avoid browser slow-down and rate limiting.

API calls format

API POST, PATCH or calls that enable you to add, amend and delete items to the basket follow the format api/v3/basket/item where 'item' is replaced by what you are adding, such as tickets or merchandise etc.

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.

Sessions

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.

JavaScript - XHR

var xhr = new XMLHttpRequest(); 
xhr.withCredentials = true; 
 
xhr.addEventListener("readystatechange", function() { 
 if(this.readyState === 4) { 
   console.log(this.responseText); 
 } 
}); 
 
xhr.open("POST", "https://customdomaingoeshere/TheClientName/api/v3/basket/tickets"); 

xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);

HTTP 200 response

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

Adding 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.

The following outlines the steps to add tickets for an event.

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

The minimum information required when adding tickets for an Event Instance with a reserved seating plan is as follows;

Instance ID
Seat ID
Ticket Type ID

If you are dealing with a group type of seating plan, you may need to use a combination of the above, depending on what area of the plan you are working with.

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.

tip

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;

Request
Response

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"
    }

Note

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.

Request
Response

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,
    }

note

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;

Request
Response

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.

Request
Response

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"
			}
		}
	]
}

Unreserved Seating Plans

Retrieve Instance Status

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;

Request
Response

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.

Request
Body
Response

POST
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 Detailed Reserved Seat Status.

Request
Response

GET
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.

Request
Body

POST
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.

note

Adding tickets via best available will adhere to the auto-distancing rules set against the instance by the client you are working with.

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:

Request
Body

POST
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. This may be particularly useful is you are adding multiple types of items to your basket at the same time.

Each type of item has a corresponding basket endpoint it must be added to.

Donations

In order to make a donation through Spektrix, the money has to be assigned to a fund.

Request
Response

GET
https://system.spektrix.com/{{clientname}}/api/v3/funds

{
	"id": "fundId",
	"name": "Fund Name",
	"description": "",
	"code": "",
	"defaultDonationAmount": 0.0
}

To POST a donation to the basket, the JSON body of the request will need to include the fund ID and the donation amount.

Request
Body

POST
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 use the following:

Request
Response

GET
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"
	}
]

And then add to the basket:

Request
Body

POST
https://system.spektrix.com/{{clientname}}/api/v3/basket/merchandise

[
	{
		"stockItem": "itemId"
	}
]

tip

It is also possible to capture a reference. The value of the reference cannot be more than 30 characters including spaces.

Memberships

To view all the available memberships use the following:

Request
Response

GET
https://system.spektrix.com/{{clientname}}/api/v3/memberships

[
	{
		"description": "",
		"htmlDescription": "",
		"id": "membershipId",
		"imageUrl": "",
		"name": "Membership Name",
		"thumbnailUrl": "",
		"price": 50,
		"renewalPrice": 45

	}
]

Send then add to the basket:

Request
Body

POST
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.

Ticket Subscriptions

To view all the available ticket subscription structures, use the following:

Request
Response

GET
https://system.spektrix.com/{{clientname}}/api/v3/ticket-subscription-structures

[
    {
        "name": "Ticket Subscription Structure name",
        "description": "",
        "onSaleWebChannel": Start Selling Date/Time,
        "onSaleWebChannelUtc": Start Selling Date/Time in UTC,
        "offSaleWebChannel": Stop Selling Date/Time,
        "offSaleWebChannelUtc": Stop Selling Date/Time in UTC,
        "pricingSets": [
            {
                "id": "ID",
                "name": "pricing set name",
                "price": 150.00
            },
            {
                "id": "ID",
                "name": "pricing set name",
                "price": 120.00
            },
            {
                "id": "ID",
                "name": "pricing set name",
                "price": 75.00
            }
        ]
    },
    {
        "name": "Ticket Subscription Structure name",
        "description": "",
        "onSaleWebChannel": Start Selling Date/Time,
        "onSaleWebChannelUtc": Start Selling Date/Time in UTC,
        "offSaleWebChannel": Stop Selling Date/Time,
        "offSaleWebChannelUtc": Stop Selling Date/Time in UTC,
        "pricingSets": [
            {
                "id": "ID",
                "name": "pricing set name",
                "price": 480.00
            }
        ]
    }
]

And then add to the basket:

Request
Body

POST
https://system.spektrix.com/{{clientname}}/api/v3/basket/ticket-subscriptions

[
  {
    "pricingSetId": "ID",
    "quantity": 2
  },
  {
    "pricingSetId": "ID",
    "quantity": 2
  }
]

You can add multiple different ticket subscriptions by including the relevant ID’s as well as different quantities for each.

warning

Note that ticket subscriptions work only with the express checkout.

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.

warning

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.

Request
Body
Response

PATCH
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 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 or the API so you could collect information via the API that doesn’t appear in the checkout iframe.

Capturing order attributes in the iframe

If the checkout iframe is set to capture order attributes, any order attributes added via the API will be overriden. You cannot collect order attributes via both iframes and API at the same time.

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.

Request
Body
Response

PATCH
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.

Request
Body
Response

PATCH
https://system.spektrix.com/{{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.

GET
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.

Delete tickets
Delete donations
Delete merch
Delete memberships

DELETE
https://system.spektrix.com/{{clientname}}/api/v3/basket/tickets?ticketIds=ticketid1,ticketid2
etc

DELETE
https://system.spektrix.com/{{clientname}}/api/v3/basket/donations?donationIds=donationid1,donationid2
etc

DELETE
https://system.spektrix.com/{{clientname}}/api/v3/basket/merchandise?merchandiseItemIds=merchandiseItemId1,merchandiseItemId2
etc

DELETE
https://system.spektrix.com/{{clientname}}/api/v3/basket/membership-subscriptions?subscriptionIds=membership1,membership2
etc

Clearing the Basket

To fully clear the basket of all contents, an empty body can be sent to v3/basket/clear.

POST
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

The Basics​

Caching​

API calls format​

Sessions​

Adding Tickets​

Events​

Instances​

Ticket Type​

Unreserved Seating Plans​

Retrieve Instance Status​

Add tickets to the Basket​

Reserved Seating Plans​

Retrieve Instance Seat Status​

Add tickets to the basket​

Best Available​

Other Items​

Donations​

Merchandise​

Memberships​

Ticket Subscriptions​

Capturing additional information for Tickets and Orders​

Ticket Attributes​

Order Attributes​

Returning the Basket​

Removing Items​

Clearing the Basket​

Things to consider​