Migration: Search to Events

Guide for migrating from the legacy GET /api/v4/search endpoint to the new GET /api/v3/events endpoint.

For the full v4 search reference, see Search on the legacy portal.

Endpoint Comparison

What Changed

From a global search to a retailer catalog you can search

The v4 endpoint took a query string and searched across every product. The v3 endpoint returns the events your retailer is set up to sell, scoped to one market, and takes an optional query to narrow that list.

locationId is required and picks the market (e.g. New York, London). Get the IDs from GET /api/v3/locations.

query is optional. It matches against event name, venue, category, cast and search keywords, up to 50 characters. Omit it, or send it blank, to list the whole catalog for the market.

# Legacy — text search
GET /api/v4/search?query=hamilton
# New — the retailer's events in one market
GET /api/v3/events?locationId=1
# New — the same list, narrowed by a search term
GET /api/v3/events?locationId=1&query=hamilton

Authentication

The affiliateId header is gone. v3 uses an API key (X-TT-API-Key), and the key itself identifies the retailer — the events you get back are the ones that key can sell. See Getting Started.

Pagination

v3 list endpoints page with limit (default 50, max 1000) and offset. The response carries a pagination block so you know when to stop. See API Conventions.

Terminology

Response Shape

Legacy (v4)

{
  "id": 456,
  "name": "Hamilton",
  "type": "show",
  "venue": { "id": "789" },
  "onSale": "true",
  "bookingStarts": "2026-03-01T00:00:00Z",
  "bookingEnds": "2026-12-31T00:00:00Z"
}

New (v3)

{
  "data": [
    {
      "id": "456",
      "name": "Hamilton",
      "displayName": "Hamilton",
      "productType": "SHOW",
      "slug": "hamilton-broadway",
      "fromPrice": { "amount": 8900, "currency": "USD" },
      "maxDiscountPercentage": 25,
      "orderLimit": { "min": 1, "max": 8 },
      "startDate": "2026-03-01",
      "endDate": "2026-12-31",
      "location": { "id": "1", "name": "New York", "country": "US", "slug": "nyc" }
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 2 }
}

Key differences:

• id is an opaque string — pass it to GET /api/v3/events/{eventId}/occurrences, never parse it (see IDs)
• startDate and endDate are both nullable — an open-ended run returns null for either. Handle both explicitly.
• The market is a location object with id, name, country, and slug, not a bare venue.id
• slug is the event’s URL path segment on the TodayTix website; it can be null for events without one
• displayName is the short name to put on a product card; name is the full title. They are often identical.
• fromPrice is the lowest regular ticket price on sale across the event’s occurrences, as a Money object in the event’s own currency (see Money). It is null when no regular tickets are on sale — a null says nothing about why.
• maxDiscountPercentage is the best discount on sale as a whole number (25 means “Save 25%”). It is omitted, not null, when there is no discount or the event does not present savings as a percentage.
• orderLimit gives the min and max ticket quantity a single order may contain. It is set per event, so apply it to the quantity selector for every occurrence.

Migration Checklist

1. Swap the affiliateId header for an X-TT-API-Key header
2. Look up the market you sell with GET /api/v3/locations, then pass it as ?locationId=
3. Keep passing your search term as query, now alongside locationId
4. Treat id as an opaque string — store it, don’t parse it
5. Read startDate / endDate instead of bookingStarts / bookingEnds; both can be null
6. Render product cards from displayName, fromPrice and maxDiscountPercentage, and bound the quantity selector with orderLimit
7. Page with limit / offset until offset >= pagination.total

Next Steps

After listing events, continue with the full Purchase Flow:

1. Browse Occurrences — GET /api/v3/events/{eventId}/occurrences (see Availability → Occurrences)
2. Browse Inventory — GET /api/v3/events/{eventId}/occurrences/{occurrenceId}/inventory-items
3. Create Cart — POST /api/v3/carts
4. Checkout — POST /api/v3/orders