> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.todaytixgroup.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.todaytixgroup.com/_mcp/server. # List occurrences for an event (browse with pricing) GET https://stg.ttix.io/api/v3/events/{eventId}/occurrences 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. Reference: https://docs.todaytixgroup.com/api-reference/browse/occurrences/get-occurrences ## Authentication - `X-TT-API-Key` header (required) — API Key authentication via header ## Servers - `https://stg.ttix.io` (Staging Environment, default) - `https://api.ttix.io` (Production Environment) ## Request ### Path parameters - `eventId` (string, required) — Event ID ### Query parameters - `quantity` (integer, optional) — 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`. - `startDate` (date, optional) — Date range start (inclusive, ISO 8601 date) - `endDate` (date, optional) — Date range end (inclusive, ISO 8601 date) - `earliestStartAt` (datetime, optional) — 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. - `latestStartAt` (datetime, optional) — The latest an occurrence in the result can start (exclusive, ISO 8601 datetime with offset). - `voucherCode` (string, optional) — 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. - `currency` (string, optional) — 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. - `limit` (integer, optional, default: 50) — Maximum number of results to return. - `offset` (integer, optional, default: 0) — Number of results to skip for pagination. ### Headers - `X-TT-Retailer` (string, required) — Your retailer identifier, provided during onboarding. It must be a retailer your API key was issued for. - `X-TT-Platform` (enum, required) — Identifies the platform the request comes from. - Allowed values: `android`, `api`, `ios`, `web` ## Response ### 200 Paginated list of occurrences with pricing. - `filters` (list of FilterResponse, required) — 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. - `data` (list of OccurrenceResponse, optional) — List of entities in the current page. - `pagination` (PaginationInfo, optional) — Pagination metadata. ## Errors ### 400 Bad Request Error Invalid parameters, a voucher that cannot be used here, or a currency the event is not sold in. - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ### 401 Unauthorized Error The request could not be authenticated. Any request gets `UNAUTHORIZED` when the `X-TT-API-Key` header is missing, and `INVALID_API_KEY` when the key is not valid or was revoked, or when the `X-TT-Retailer` header is missing or names a retailer the key cannot be used for. - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ### 403 Forbidden Error The request is not allowed from where it was sent. Any request sent from a web page gets `ORIGIN_NOT_ALLOWED` when the page's origin is not one the API key allows. Add the origin to the key, or use a key that allows it. A request with no `Origin` header, such as one from your server, is never refused for this. - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ### 404 Not Found Error Event not found - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ### 429 Too Many Requests Error Too many requests. Wait at most the number of seconds in the `Retry-After` header when it is present, then send the request again. - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ### 500 Internal Server Error Internal server error - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ### 503 Service Unavailable Error The requested currency is sold here but cannot be priced right now (no exchange rate). Retry shortly. - `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display. ## Types ### FilterResponse A filter category and the options available for it on this event. - `type` (enum, required) — The dimension a filter narrows occurrences by. New filter types may be added over time — ignore an entry whose type you do not recognize rather than treating it as an error. - Allowed values: `SECTION` - `label` (string, required) — Display name of the filter category. - `options` (list of FilterOptionResponse, required) — Options available for this filter, in display order. Empty when the event has nothing to filter by on this dimension. ### OccurrenceResponse A dated occurrence of an event, with its venue, availability and price summary. - `admissionType` (enum, required) — How admission works for this occurrence. TIMED means entry on a specific day at a specific time. DATED means entry on a specific day, any time between open and close. OPEN means entry on any day at any time. SLOT means entry at any time between the start and end times. On an event that grants no admission — a gift card — the value is a placeholder and carries no meaning; do not show admission details for one. - Allowed values: `TIMED`, `DATED`, `OPEN`, `SLOT` - `id` (string, required) — Unique identifier for the occurrence - `orderLimit` (OrderLimitResponse, required) — Bounds on the ticket quantity a single order may contain. The same value as the event's `orderLimit`. - `startsAt` (datetime, required) — Start date and time of the occurrence in ISO 8601 with venue timezone offset. On an event that does not happen at a time — a gift card — this is a placeholder, not a date to show a shopper. - `venue` (VenueSimpleResponse, required) — Venue where the occurrence takes place. Always present, but an event with no theatre behind it — a gift card — returns one whose `id` and `name` are null. - `availabilityLevel` (enum, optional, nullable) — How much availability remains for this occurrence. SOLD_OUT means no tickets are currently available for purchase (relative to the requested quantity when provided). LOW means tickets are running out. Null means no availability signal — display the occurrence normally. New values may be added over time; treat any unrecognized value as no signal. - Allowed values: `LOW`, `SOLD_OUT` - `doorsOpen` (DoorsOpenResponse, optional, nullable) — When doors open at the venue before the occurrence starts. Omitted when no doors-open time is available. - `endsAt` (datetime, optional, nullable) — End date and time of the occurrence in ISO 8601 with venue timezone offset. Null for events without a fixed end time. - `fromPrice` (Money, optional, nullable) — Lowest available ticket price. Null when nothing is on sale for this occurrence (sold out, off sale, or not yet on sale). - `maxDiscountAmount` (Money, optional) — Maximum discount amount available for this occurrence. Omitted when no discount is available. - `maxDiscountPercentage` (integer, optional) — Maximum discount percentage available for this occurrence. Omitted when no discount is available. - `notices` (list of NoticeResponse, optional) — Notices about this occurrence, such as cast changes or accessibility services. Omitted when there are none. - `promotions` (list of PromotionSimpleResponse, optional) — Active promotions for this occurrence. Omitted when no promotions apply. - `venueMap` (VenueMapResponse, optional, nullable) — Venue map/seating chart for inventory selection. Omitted for general-admission-only or open seating events. ### PaginationInfo Pagination information for paginated responses - `limit` (integer, optional) — Maximum number of results per page - `offset` (integer, optional) — Number of results skipped for pagination - `total` (long, optional) — Total number of results available ### ErrorResponse What went wrong: `type` and `code` for your code to act on, `message` to display. - `type` (enum, required) — High-level error category. - Allowed values: `INVALID_REQUEST_ERROR`, `AUTHENTICATION_ERROR`, `PAYMENT_ERROR`, `PERMISSION_ERROR`, `NOT_FOUND_ERROR`, `METHOD_NOT_ALLOWED_ERROR`, `CONFLICT_ERROR`, `RESOURCE_GONE_ERROR`, `PRECONDITION_FAILED_ERROR`, `UNSUPPORTED_MEDIA_TYPE_ERROR`, `PRECONDITION_REQUIRED_ERROR`, `RATE_LIMIT_ERROR`, `API_ERROR`, `SERVICE_UNAVAILABLE` - `code` (enum, required) — Machine-readable error code. - Allowed values: `METHOD_NOT_ALLOWED`, `UNSUPPORTED_MEDIA_TYPE`, `INVALID_FIELD_VALUE`, `ACCESS_CARD_NOT_VERIFIED`, `ACCESS_CARD_WRONG_SCHEME`, `ACCESS_VERIFICATION_NOT_SUPPORTED`, `ACCESS_VERIFICATION_UNAVAILABLE`, `TICKET_ALERT_SIGNUP_NOT_SUPPORTED`, `MIXED_ITEM_TYPES_NOT_SUPPORTED`, `INVALID_VOUCHER`, `CURRENCY_NOT_SUPPORTED`, `CURRENCY_TEMPORARILY_UNAVAILABLE`, `MISSING_REQUIRED_HEADER`, `MISSING_REQUIRED_FIELD`, `UNAUTHORIZED`, `INVALID_API_KEY`, `INVALID_ACCESS_TOKEN`, `PAYMENT_AUTHENTICATION_REQUIRED`, `PAYMENT_DECLINED`, `RISK_CHECK_FAILED`, `APPLE_PAY_NOT_AVAILABLE`, `APPLE_PAY_SESSION_UNAVAILABLE`, `INVALID_REQUEST`, `RESOURCE_NOT_FOUND`, `INSUFFICIENT_PERMISSIONS`, `ORIGIN_NOT_ALLOWED`, `RATE_LIMITED`, `INTERNAL_SERVER_ERROR`, `SERVICE_UNAVAILABLE`, `PRICE_CHANGED`, `INVENTORY_EXHAUSTED`, `OCCURRENCE_NOT_AVAILABLE`, `OCCURRENCE_NOT_COMPATIBLE`, `ORPHANED_SEATS`, `INVALID_PRICE_OPTION`, `MIXED_OCCURRENCES_NOT_SUPPORTED`, `EVENT_NOT_SELLABLE`, `MIXED_PRODUCT_TYPES_NOT_SUPPORTED`, `MULTIPLE_GIFT_CARDS_NOT_SUPPORTED`, `GIFT_CARD_QUANTITY_NOT_SUPPORTED`, `MINIMUM_QUANTITY_NOT_MET`, `EVENT_MINIMUM_NOT_MET`, `VOUCHER_NOT_APPLICABLE_TO_GIFT_CARD`, `CART_EXPIRED`, `EXPECTED_TOTAL_MISMATCH`, `TICKET_LIMIT_EXCEEDED`, `PAYMENT_METHOD_NOT_AVAILABLE`, `CART_ALREADY_ORDERED`, `CART_CUSTOMER_REQUIRED`, `CART_ALREADY_CLAIMED`, `INVALID_IDEMPOTENCY_KEY`, `IDEMPOTENCY_KEY_ALREADY_PROCESSING`, `IDEMPOTENCY_KEY_CART_MISMATCH`, `IDEMPOTENCY_KEY_FAILED`, `GRANT_NOT_CLAIMABLE`, `GRANT_NOT_CANCELLABLE`, `WALLET_PASS_DOWNLOAD_BLOCKED`, `ACTION_NOT_AVAILABLE`, `WALLET_PASS_CHANGED`, `WALLET_PASS_NOT_ISSUED`, `WALLET_PASS_REPLACEMENT_NOT_SUPPORTED`, `WALLET_PASS_REPLACEMENT_UNFINISHED`, `WALLET_PASS_REPLACEMENT_NEEDS_SUPPORT`, `VERSION_REQUIRED`, `THIRD_PARTY_OUTAGE` - `message` (string, required) — Human-readable description of the error. - `param` (string, optional, nullable) — The request field that caused the error, if applicable. - `details` (map from string to ErrorResponseDetails, optional, nullable) — Additional structured data for client recovery logic. ### FilterOptionResponse One value a customer can filter occurrences by. - `id` (string, required) — Identifier of the option, stable across requests for the same event. - `label` (string, required) — Display name of the option. ### OrderLimitResponse Bounds on the ticket quantity a single order for this event may contain. - `max` (integer, required) — Most tickets one order may contain. - `min` (integer, required) — Fewest tickets one order must contain. ### VenueSimpleResponse Venue where the occurrence takes place - `address` (AddressResponse, optional, nullable) — Structured postal address. Omitted when address data is unavailable. - `id` (string, optional, nullable) — Stable venue identifier. - `name` (string, optional, nullable) — Display name of the venue - `timezone` (string, optional, nullable) — IANA timezone identifier for the venue. ### DoorsOpenResponse When doors open at the venue for this occurrence. - `at` (datetime, required) — Date and time when doors open, in ISO 8601 with venue timezone offset. - `description` (string, optional, nullable) — Customer-facing copy about doors opening. Omitted when there is none. ### Money Monetary amount: an integer in minor units (cents for USD) with its currency code. - `amount` (long, required) — Amount in minor units (cents for USD, pence for GBP, etc.) - `currency` (string, required) — ISO 4217 currency code ### NoticeResponse A notice about this occurrence, such as a cast change or an accessibility service. - `name` (string, required) — Short title of the notice. - `description` (string, optional, nullable) — Longer text with the detail of the notice. Omitted when there is no extra detail. ### PromotionSimpleResponse Lightweight promotion reference for occurrence-level summaries. - `id` (string, required) — Stable promotion identifier. - `name` (string, required) — Promotion display name. ### VenueMapResponse Venue map/seating chart for inventory selection - `id` (string, required) — Venue chart key for seating chart rendering ### ErrorResponseDetails Additional structured data for client recovery logic. ### AddressResponse Structured postal address for venue display - `line1` (string, optional, nullable) — First line of the street address - `line2` (string, optional, nullable) — Second line of the street address (suite, floor, etc.) - `city` (string, optional, nullable) — City name - `state` (string, optional, nullable) — State, province, or region - `postalCode` (string, optional, nullable) — Postal or ZIP code - `country` (string, optional, nullable) — ISO 3166-1 alpha-2 country code - `latitude` (double, optional, nullable) — Latitude coordinate - `longitude` (double, optional, nullable) — Longitude coordinate ## Examples **Response** ```json { "filters": [ { "type": "SECTION", "label": "Section", "options": [ { "id": "1204", "label": "Orchestra" }, { "id": "1205", "label": "Mezzanine" } ] } ], "data": [ { "admissionType": "TIMED", "id": "123", "orderLimit": { "max": 8, "min": 1 }, "startsAt": "2026-03-15T19:30:00-04:00", "venue": { "address": { "line1": "226 W 46th St", "city": "New York", "state": "NY", "postalCode": "10036", "country": "US" }, "id": "UmljaGFyZCBSb2RnZXJzIFRoZWF0cmU=", "name": "Richard Rodgers Theatre", "timezone": "America/New_York" }, "availabilityLevel": null, "endsAt": "2026-03-15T22:30:00-04:00", "fromPrice": { "amount": 8500, "currency": "USD" }, "maxDiscountAmount": { "amount": 3000, "currency": "USD" }, "maxDiscountPercentage": 25, "venueMap": { "id": "abc123-chart-key" } }, { "admissionType": "TIMED", "id": "124", "orderLimit": { "max": 8, "min": 1 }, "startsAt": "2026-03-16T14:00:00-04:00", "venue": { "address": { "line1": "226 W 46th St", "city": "New York", "state": "NY", "postalCode": "10036", "country": "US" }, "id": "UmljaGFyZCBSb2RnZXJzIFRoZWF0cmU=", "name": "Richard Rodgers Theatre", "timezone": "America/New_York" }, "availabilityLevel": "LOW", "endsAt": "2026-03-16T16:30:00-04:00", "fromPrice": { "amount": 9500, "currency": "USD" }, "maxDiscountAmount": { "amount": 5000, "currency": "USD" } }, { "admissionType": "TIMED", "id": "125", "orderLimit": { "max": 8, "min": 1 }, "startsAt": "2026-03-16T19:30:00-04:00", "venue": { "address": { "line1": "226 W 46th St", "city": "New York", "state": "NY", "postalCode": "10036", "country": "US" }, "id": "UmljaGFyZCBSb2RnZXJzIFRoZWF0cmU=", "name": "Richard Rodgers Theatre", "timezone": "America/New_York" }, "availabilityLevel": "SOLD_OUT", "fromPrice": null } ], "pagination": { "limit": 50, "offset": 0, "total": 3 } } ``` **SDK Code** ```python Occurrences_getOccurrences_example import requests url = "https://stg.ttix.io/api/v3/events/123/occurrences" querystring = {"quantity":"2","startDate":"2026-03-15","endDate":"2026-03-31","earliestStartAt":"2026-03-15T10:00:00-04:00","latestStartAt":"2026-03-15T22:30:00-04:00","voucherCode":"PRESALE24","currency":"GBP","limit":"50","offset":"0"} headers = { "X-TT-Retailer": "YOUR_RETAILER_ID", "X-TT-Platform": "android", "X-TT-API-Key": "" } response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript Occurrences_getOccurrences_example const url = 'https://stg.ttix.io/api/v3/events/123/occurrences?quantity=2&startDate=2026-03-15&endDate=2026-03-31&earliestStartAt=2026-03-15T10%3A00%3A00-04%3A00&latestStartAt=2026-03-15T22%3A30%3A00-04%3A00&voucherCode=PRESALE24¤cy=GBP&limit=50&offset=0'; const options = { method: 'GET', headers: { 'X-TT-Retailer': 'YOUR_RETAILER_ID', 'X-TT-Platform': 'android', 'X-TT-API-Key': '' } }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Occurrences_getOccurrences_example package main import ( "fmt" "net/http" "io" ) func main() { url := "https://stg.ttix.io/api/v3/events/123/occurrences?quantity=2&startDate=2026-03-15&endDate=2026-03-31&earliestStartAt=2026-03-15T10%3A00%3A00-04%3A00&latestStartAt=2026-03-15T22%3A30%3A00-04%3A00&voucherCode=PRESALE24¤cy=GBP&limit=50&offset=0" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("X-TT-Retailer", "YOUR_RETAILER_ID") req.Header.Add("X-TT-Platform", "android") req.Header.Add("X-TT-API-Key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Occurrences_getOccurrences_example require 'uri' require 'net/http' url = URI("https://stg.ttix.io/api/v3/events/123/occurrences?quantity=2&startDate=2026-03-15&endDate=2026-03-31&earliestStartAt=2026-03-15T10%3A00%3A00-04%3A00&latestStartAt=2026-03-15T22%3A30%3A00-04%3A00&voucherCode=PRESALE24¤cy=GBP&limit=50&offset=0") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["X-TT-Retailer"] = 'YOUR_RETAILER_ID' request["X-TT-Platform"] = 'android' request["X-TT-API-Key"] = '' response = http.request(request) puts response.read_body ``` ```java Occurrences_getOccurrences_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://stg.ttix.io/api/v3/events/123/occurrences?quantity=2&startDate=2026-03-15&endDate=2026-03-31&earliestStartAt=2026-03-15T10%3A00%3A00-04%3A00&latestStartAt=2026-03-15T22%3A30%3A00-04%3A00&voucherCode=PRESALE24¤cy=GBP&limit=50&offset=0") .header("X-TT-Retailer", "YOUR_RETAILER_ID") .header("X-TT-Platform", "android") .header("X-TT-API-Key", "") .asString(); ``` ```php Occurrences_getOccurrences_example request('GET', 'https://stg.ttix.io/api/v3/events/123/occurrences?quantity=2&startDate=2026-03-15&endDate=2026-03-31&earliestStartAt=2026-03-15T10%3A00%3A00-04%3A00&latestStartAt=2026-03-15T22%3A30%3A00-04%3A00&voucherCode=PRESALE24¤cy=GBP&limit=50&offset=0', [ 'headers' => [ 'X-TT-API-Key' => '', 'X-TT-Platform' => 'android', 'X-TT-Retailer' => 'YOUR_RETAILER_ID', ], ]); echo $response->getBody(); ``` ```csharp Occurrences_getOccurrences_example using RestSharp; var client = new RestClient("https://stg.ttix.io/api/v3/events/123/occurrences?quantity=2&startDate=2026-03-15&endDate=2026-03-31&earliestStartAt=2026-03-15T10%3A00%3A00-04%3A00&latestStartAt=2026-03-15T22%3A30%3A00-04%3A00&voucherCode=PRESALE24¤cy=GBP&limit=50&offset=0"); var request = new RestRequest(Method.GET); request.AddHeader("X-TT-Retailer", "YOUR_RETAILER_ID"); request.AddHeader("X-TT-Platform", "android"); request.AddHeader("X-TT-API-Key", ""); IRestResponse response = client.Execute(request); ``` ```swift Occurrences_getOccurrences_example import Foundation let headers = [ "X-TT-Retailer": "YOUR_RETAILER_ID", "X-TT-Platform": "android", "X-TT-API-Key": "" ] let request = NSMutableURLRequest(url: NSURL(string: "https://stg.ttix.io/api/v3/events/123/occurrences?quantity=2&startDate=2026-03-15&endDate=2026-03-31&earliestStartAt=2026-03-15T10%3A00%3A00-04%3A00&latestStartAt=2026-03-15T22%3A30%3A00-04%3A00&voucherCode=PRESALE24¤cy=GBP&limit=50&offset=0")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```