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

This endpoint complements Creating Event Instances using API v3 Owner Mode and supports selecting overlays that cannot be supplied during creation.

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

Important limitations

• The Event the instance belongs to (eventId) cannot be changed.
• The seating plan (planId) cannot be changed.
• Overlays can be changed only to overlays belonging to the instance's existing seating plan.
• Only supplied properties are changed. Omitted properties are left unchanged, and there is no way to reset a property to a system default.
• Layout and lock overlays can fail against existing sales or locks. If an overlay conflicts with the current seating, the request is rejected and nothing is saved.
• Price-band overlay and price-list compatibility is not validated. Confirm compatibility using the template endpoint before sending the request.

Example request

PATCH api/v3/instances/{id}

{
  "start": "2026-09-15T20:00:00",
  "priceListId": "10803AGLDJVGTVPHNTKTJJBCHQNDNRCGT",
  "priceBandOverlayId": "11815ARTRLRTQKLGRSNGJBGSCGSGLNCNC",
  "status": "Live",
  "sellInWeb": true,
  "stopSellingAtWeb": "2026-09-15T19:00:00",
  "Attribute_Special Performance": "Press Night",
  "Attribute_Weighting": "5"
}

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

Partial updates

PATCH applies only the properties present in the JSON body:

• A property that is present is applied, even if its value is the same as the current value.
• A property that is absent is left untouched.
• There are no required properties. An empty JSON object {} is valid and changes nothing.
• A request with no JSON body returns 400 Bad Request with the message request body is required.

Updatable properties

Property	Description
start	Local start date and time of the Event Instance.
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.
ticketDesignId	Ticket design to use.
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.
isCancelled	Whether the Event Instance is cancelled.
levyAmount	Levy amount.
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.
priceBandOverlayId	Price-band overlay to apply. It must belong to the instance's seating plan.
layoutOverlayId	Layout overlay to apply. It must belong to the instance's seating plan.
lockOverlayId	Lock overlay to apply. It must belong to the instance's seating plan.
infoOverlayId	Info overlay to apply, or an empty string to clear it.
bestAvailableOverlayId	Best-available overlay to apply, or an empty string to clear it.
Attribute_*	Values for configured Event Instance attributes. Use property values from the template response.

Event Instance attributes

Attributes are patched in the same way as they are supplied to POST: use the value of property from the template response as the JSON property name and provide the value.

{
  "Attribute_Special Performance": "Press Night"
}

When patching attributes:

• Supplied attributes are merged over the instance's existing attributes. Attributes you do not mention are unchanged.
• Supplying an empty string clears an attribute's value.
• Attribute names containing spaces are supported.
• If no attributes are supplied, the instance's attributes are not changed.

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

Overlays

Unlike POST, PATCH accepts overlay IDs. This is the route for integrations that need something other than the seating plan's automatically selected overlays.

Property	Description
layoutOverlayId	Applies the layout overlay. Rejected if existing sales or locks conflict with it.
lockOverlayId	Applies the lock overlay. Rejected if it cannot be applied to one or more areas of the seating plan.
priceBandOverlayId	Applies the price-band overlay. Check price-list compatibility first.
infoOverlayId	Applies the info overlay. Supply an empty string to remove it.
bestAvailableOverlayId	Applies the best-available overlay. Supply an empty string to remove it.

The following rules apply to all overlays:

• The overlay must belong to the instance's seating plan.
• Layout and lock overlays are applied against the instance's current seating, so an overlay that was valid on an empty instance may be rejected once seats have been sold or locked.
• Overlays are changed only when their properties are supplied. Omitting them leaves the current overlays in place.

Before changing a price-band overlay, confirm that it is compatible with the selected price list. Problems may occur if the overlay contains price bands that are not configured in the price list.

Visibility and selling rules

The visibility and selling flags must form a valid combination and follow the same rules as when creating an Event Instance. A request containing an invalid combination returns all applicable validation errors, rather than only the first.

Selling-time ordering

Supplied values are evaluated against the instance's existing start and stop selling times:

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

For example, setting startSellingAtSales on an instance that has no web selling start time is rejected while web selling is enabled. Supply both values in the same request.

E-ticket rules

• An e-ticket PDF template requires an e-ticket design.
• An e-ticket design requires an e-ticket PDF template.

If the instance already has an e-ticket design, you may patch the PDF template on its own. If it has neither, supply both in the same request.

Successful response

A successful patch returns 200 OK. The response body contains the updated API v3 Event Instance resource in the same format as GET /api/v3/instances/{id}.

Error responses

Status	Meaning
400 Bad Request	The request body is missing, a property is unrecognized, a value or reference is invalid, an overlay does not belong to the instance's seating plan, an overlay cannot be applied, selling flags conflict, or selling times are not in a valid order.
404 Not Found	The Event Instance id in the route 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.

Nothing is saved when a request fails. Reference resolution, validation, and overlay application happen before the change is committed, so a rejected patch leaves the Event Instance as it was.

Do not use this preview to test changing an instance's Event or seating plan. These operations are not supported.