Skip to navigation
API ReferenceBrowseOccurrences

List occurrences for an event (browse with pricing)

Returns a paginated list of occurrences for an event with pricing information for browse/selection UI.

Pricing fields (per occurrence):

  • fromPrice — Lowest available price (null when sold out or off-sale)
  • maxDiscountAmount — Max discount amount (always present when a discount exists)
  • maxDiscountPercentage — Max discount percentage (present only when event allows percentage display)

Key behaviors:

  • Sold-out occurrences are included, with availabilityLevel: "SOLD_OUT" and fromPrice: null, unless the event or your retailer account is set to list only dates with something on sale (for example, to hide dates that are not announced yet). Then every occurrence with nothing to buy is left out, and pagination.total does not count it
  • An occurrence whose tickets are all held back from your retailer account, for example kept for another seller, is left out rather than shown as sold out, and pagination.total does not count it
  • availabilityLevel signals remaining availability: LOW, SOLD_OUT, or null when there is no signal
  • When quantity is set, availability and pricing reflect only inventory that can seat that many tickets together
  • Discount may be from a different price point than fromPrice (represents max savings)

Send the voucherCode query parameter with a presale or access code to see the dates that code unlocks, with availability and pricing from the inventory the code gates.

Filters: filters lists the ways a customer can narrow these occurrences, each with its options. A SECTION filter lists the sections this event sells, with no options for an event that does not offer filtering by section.

Authentication

X-TT-API-Keystring
API Key authentication via header

Path parameters

eventIdstringRequired>=1 character
Event ID

Headers

X-TT-RetailerstringRequired
Your retailer identifier, provided during onboarding. It must be a retailer your API key was issued for.
X-TT-PlatformenumRequired
Identifies the platform the request comes from.
Allowed values:

Query parameters

quantityintegerOptional

Number of tickets the party needs. Pricing and availabilityLevel then reflect only inventory that can seat this many tickets together — an occurrence without enough seats reads as SOLD_OUT.

startDatedateOptional

Date range start (inclusive, ISO 8601 date)

endDatedateOptional

Date range end (inclusive, ISO 8601 date)

earliestStartAtdatetimeOptional

The earliest an occurrence in the result can start (inclusive, ISO 8601 datetime with offset). Use alongside or instead of startDate/endDate to filter to a precise time range rather than whole calendar days — e.g. a scheduled extra’s own bookable window on a given day.

latestStartAtdatetimeOptional

The latest an occurrence in the result can start (exclusive, ISO 8601 datetime with offset).

voucherCodestringOptionalformat: ".*\S.*"0-15 characters
Presale or access code the shopper has entered. Availability and pricing then come from the inventory that code unlocks, priced with the code applied. Invalid codes and codes without a campaign return 400. A campaign without availability also returns 400, unless the requested range has no occurrences. A blank code, or one longer than 15 characters, is rejected with a 400.
currencystringOptionalformat: "^[A-Z]{3}$"

ISO 4217 currency to price in. Omit for the event base currency. A currency this event is not sold in returns 400; one it is sold in but that cannot be priced right now returns 503.

limitintegerOptional1-1000Defaults to 50
Maximum number of results to return.
offsetintegerOptional>=0Defaults to 0
Number of results to skip for pagination.

Response headers

X-RateLimit-Limitinteger
How many requests this API key may make for this retailer in the current window. Sent only when the request was counted against that limit. A response served from cache was not counted and repeats the value it was cached with.
X-RateLimit-Remaininginteger
How many requests this API key has left for this retailer in the current window. Sent only when the request was counted against that limit. A response served from cache was not counted and repeats the value it was cached with.

Response

Paginated list of occurrences with pricing.
filterslist of objects
Filters a customer can narrow these occurrences by, in display order. Computed for the whole event, so every page of the same query carries the same filters.
datalist of objectsOptional
List of entities in the current page.
paginationobjectOptional
Pagination metadata.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error