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 free-text search to a retailer catalog

The v4 endpoint took a query string and searched across products. The v3 endpoint returns the events your retailer is set up to sell, filtered by market. You no longer search by name — you list what you can sell and filter it yourself.

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

# Legacy — text search
GET /api/v4/search?query=hamilton
# New — the retailer's events in one market
GET /api/v3/events?locationId=1

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)

1
{
2
  "id": 456,
3
  "name": "Hamilton",
4
  "type": "show",
5
  "venue": { "id": "789" },
6
  "onSale": "true",
7
  "bookingStarts": "2026-03-01T00:00:00Z",
8
  "bookingEnds": "2026-12-31T00:00:00Z"
9
}

New (v3)

1
{
2
  "data": [
3
    {
4
      "id": "456",
5
      "name": "Hamilton",
6
      "startDate": "2026-03-01",
7
      "endDate": "2026-12-31",
8
      "location": { "id": "1", "name": "New York", "country": "US" }
9
    }
10
  ],
11
  "pagination": { "limit": 50, "offset": 0, "total": 2 }
12
}

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, and country, not a bare venue.id

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. Replace text search with client-side filtering over the returned events
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. 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