Creating Event Instances

Early Access

This functionality is available under early access. Its behavior or response format may change before general availability and it may require additional configuration by the Spektrix team to access it. Contact us if you plan to use it in a production integration.

API v3 System Owner mode provides an early version of the functionality required to create Event Instances programmatically. This preview contains three endpoints:

1. GET /api/v3/instances/template returns the IDs, codes, and options that can be used when creating an Event Instance.
2. POST /api/v3/instances creates a new Event Instance.
3. PATCH /api/v3/instances/{id} updates an existing Event Instance.

These endpoints are available only to integrations authenticated in API v3 System Owner mode. For more detail on signing requests, see Authentication.

We particularly welcome early-access feedback about whether the template contains all the information needed to construct a request, whether field names and validation messages are clear, whether the defaults are suitable, and whether the workflow reduces manual setup in Spektrix.

Preview limitations

• Always provide planId. The preview may select the first configured seating plan when it is omitted, but this fallback is not part of the intended contract and will be removed.
• The planId cannot be changed after an Event Instance has been created.
• POST does not accept overlay IDs. It applies the first active price-band, layout, and lock overlays for the seating plan, sorted alphabetically by name, where available.
• Confirm that the selected price list is compatible with the automatically selected price-band overlay.
• To use alternative overlays, create the Event Instance and then use the PATCH endpoint.
• Initially create Event Instances with status set to Draft, then check their configuration in Spektrix before making them Live.

Prerequisites

Before testing these endpoints, you need:

• API v3 credentials with System Owner mode access.
• An existing Event, which can also be created using API v3.
• A seating plan selected explicitly using planId.
• Active layout, lock, and price-band overlays configured for that seating plan.
• A price list compatible with the automatically selected price-band overlay.
• A commission structure.
• A tax code.

In this preview, the default overlay means the first active overlay when overlays are sorted alphabetically by name; it is not an explicitly configured setting. The template lists active overlays but does not identify which one will be selected. Do not rely on the JSON property order. Sort overlays by name, or preferably confirm the expected overlay in Spektrix Admin.

The easiest way to obtain the relevant IDs and codes is to call the template endpoint first. For initial testing, use a known-good seating plan and price-list combination that your ticketing team has verified in Spektrix.

Step 1: Retrieve the Event Instance template

GET /api/v3/instances/template

GET /api/v3/instances/template

Template properties

Property	Description
seatingPlans	Seating plans that may be used for the Event Instance, including their active overlays.
priceListIds	Price-list IDs and display names.
taxCodes	Tax codes and descriptions.
commissionStructures	Commission-structure IDs and names.
ticketDesignIds	Ticket-design IDs and names.
eticketPdfTemplateIds	E-ticket PDF-template IDs and names.
attributes	Event Instance attributes configured in the system.

When creating an Event Instance, select the seating plan explicitly using planId. Although each seating plan in the template includes its configured overlays, POST does not currently accept overlay IDs.

Event Instance attributes

The template's attributes collection contains attribute definitions for reference. Do not include the definition fields in the POST request. Instead, use the value of property as the JSON property name and provide the relevant attribute value.

For example, if the template contains:

{
  "property": "Attribute_Special Performance",
  "name": "Special Performance",
  "type": "DropDown",
  "isRequired": false,
  "options": ["Press Night", "Relaxed Performance"]
}

Supply the selected value in the POST request as:

{
  "Attribute_Special Performance": "Press Night"
}

Each attribute definition can contain:

Property	Meaning
property	The JSON property name to use in the request.
name	The attribute's display name in Spektrix. This is not sent in the request.
description	The configured description. This is not sent in the request.
type	The expected value type.
isRequired	Whether the request must provide a value for this attribute.
maxLength	The maximum permitted length for a text value, where applicable.
options	The permitted values for a dropdown attribute.
dropDownAllowsFreeText	Whether a dropdown accepts values other than those listed in options.

Retrieve the template before constructing a request because configured attributes and their validation requirements may change.

Step 2: Create the Event Instance

Example request

POST api/v3/insatnces

{
  "eventId": "3803APLHKHLHGKTNBRTKBMRGDKVTVTVPD",
  "start": "2026-09-15T19:30:00",
  "planId": "11815ARTRLRTQKLGRSNGJBGSCGSGLNCNC",
  "priceListId": "10803AGLDJVGTVPHNTKTJJBCHQNDNRCGT",
  "commissionStructureId": "13800ATKCPSQDCDSLVDPPDDHLCHPJTNJJ",
  "taxCode": "S",
  "ticketDesignId": "TICKET_DESIGN_ID",
  "eTicketDesignId": "ETICKET_DESIGN_ID",
  "eticketPdfTemplateId": "ETICKET_PDF_TEMPLATE_ID",
  "status": "Draft",
  "isCancelled": false,
  "levyAmount": 0.00,
  "showInSales": true,
  "showInWeb": true,
  "showInAgent": true,
  "showInFundraising": false,
  "sellInSales": true,
  "sellInWeb": true,
  "sellInAgent": true,
  "sellInFundraising": false,
  "webInstanceId": "preview-15-sep",
  "Attribute_Special Performance": "Press Night"
}

Replace the example IDs and attribute properties with values from your system and the template response.

Required properties

Property	Description
eventId	ID of the existing Event to which the new instance belongs.
start	Local start date and time of the Event Instance.
planId	Seating-plan ID from the template. Always supply this during the preview.
priceListId	Price-list ID from the template.
commissionStructureId	Commission-structure ID from the template.
taxCode	Tax code from the template.
showInSales	Whether the instance is visible in Sales.
showInWeb	Whether it is visible on the web.
showInAgent	Whether it is visible to Agents.
showInFundraising	Whether it is visible in Fundraising.
sellInSales	Whether tickets can be sold in Sales.
sellInWeb	Whether tickets can be sold on the web.
sellInAgent	Whether tickets can be sold by Agents.
sellInFundraising	Whether tickets can be sold through Fundraising.

Optional properties

Property	Description and default
ticketDesignId	Ticket design to use. If omitted, the API selects the first configured ticket design. We recommend supplying this explicitly.
eTicketDesignId	E-ticket design to use. If supplied, eticketPdfTemplateId is also required.
eticketPdfTemplateId	E-ticket PDF template to use. If supplied, eTicketDesignId is also required.
status	Draft, Live, or Archived. Defaults to Draft.
isCancelled	Whether the Event Instance is cancelled. Defaults to false.
levyAmount	Levy amount. Defaults to zero.
webInstanceId	Optional web-facing identifier. Maximum 20 characters.
startSellingAtSales	Time at which Sales selling begins.
startSellingAtWeb	Time at which web selling begins.
startSellingAtAgent	Time at which Agent selling begins.
startSellingAtFundraising	Time at which Fundraising selling begins.
stopSellingAtSales	Time at which Sales selling stops.
stopSellingAtWeb	Time at which web selling stops.
stopSellingAtAgent	Time at which Agent selling stops.
stopSellingAtFundraising	Time at which Fundraising selling stops.
Attribute_*	Values for configured Event Instance attributes. Use property values from the template response.

Default stop-selling times

If stop-selling times are omitted, the following defaults apply:

Interface	Default
Sales	24 hours after the Event Instance starts.
Web	60 minutes before the Event Instance starts.
Agent	60 minutes before the Event Instance starts.
Fundraising	No default stop-selling time.

Visibility and selling rules

The visibility and selling flags must form a valid combination:

• An instance cannot be shown on the web unless it is also shown in Sales.
• It cannot be shown to Agents unless it is also shown on the web.
• Sales selling requires Sales visibility.
• Web selling requires both web visibility and Sales selling.
• Agent selling requires Agent visibility and web selling.
• Fundraising selling requires Fundraising visibility.

A request containing an invalid combination returns a validation error.

Selling-time ordering

Where the corresponding values are supplied:

• Web selling must not start before Sales selling.
• Agent selling must not start before web selling.
• Web selling must stop before Sales selling.
• Agent selling must stop before web selling.

Default seating-plan overlays

You do not provide overlay IDs during creation. The API automatically applies the selected seating plan's first active layout, lock, and price-band overlays when sorted alphabetically by name, where available.

Before using POST, confirm that the automatically selected price-band overlay is appropriate for the supplied price list. Problems may occur if the overlay contains price bands that are not configured in the selected price list.

For initial testing:

1. Use a simple, known-good set of overlays.
2. Use a price list that your ticketing team has confirmed is compatible with the price-band overlay.
3. Create the Event Instance with status set to Draft.
4. Inspect the resulting Event Instance in Spektrix before making it Live.
5. If required, select alternative overlays using Updating Event Instances using API v3 Owner Mode.

Successful response

A successful request returns 201 Created. The response body contains the newly created API v3 Event Instance resource in the same format as GET /api/v3/instances/{id}.

Store the returned id so that you can retrieve or update the Event Instance later.

Error responses

Status	Meaning
400 Bad Request	The request body is missing, a required value is missing, a value is invalid, selling flags conflict, or selling times are not in a valid order. See the known planId exception below.
404 Not Found	A referenced resource, such as the Event, seating plan, price list, or commission structure, could not be found.
401 Unauthorized	The credentials do not permit use of this System Owner mode endpoint.

A request with no JSON body returns 400 Bad Request.

Known planId exception

Although planId is required for this early-access workflow, the current preview may not return 400 Bad Request when it is omitted. It may select the first configured seating plan instead. Always provide planId; this fallback will be removed before the API contract is finalized.