Migrating from V1 to V2

V1 is deprecated but still supported. There is no sunset date, so existing V1 integrations keep working. New integrations should build on V2; existing V1 integrations should plan to migrate when convenient. This page walks through what changes, area by area, and what you need to do in each case.

​

Before you start

A few things are not changing:

• The Headout-Auth header.
• Sandbox and production hosts.
• Sandbox / production key prefixes (tk_ / pk_).
• The booking status enum (UNCAPTURED, PENDING, COMPLETED, CANCELLED, FAILED, CAPTURE_TIMEDOUT).
• The two-step capture flow (Create → Update with status: "PENDING").

If your integration handled these in V1, no changes are needed.

​

Step 1 — Catalog discovery

​

What changed

V1 paths were verb-style and shallow:

• GET /api/public/v1/city
• GET /api/public/v1/category/list-by/city

V2 paths are resource-style and add two new levels of grouping:

• GET /api/public/v2/cities/
• GET /api/public/v2/categories
• GET /api/public/v2/collections — new in V2. Themed groupings like “Broadway Shows” or “Statue of Liberty.”
• GET /api/public/v2/subcategories — new in V2. Finer cuts under a category, like “Museums” or “Landmarks.”

​

What to do

• Swap the V1 city and category endpoints for their V2 equivalents. cityCode is now a query parameter.
• Collections and subcategories are optional. You can ignore them and keep your existing city → category → product UI. Adopt them later if you want richer browsing.

​

Step 2 — Listing and fetching products

​

What changed

V1 had two product listing endpoints:

• GET /api/public/v1/product/listing/list-by/city
• GET /api/public/v1/product/listing/list-by/category

V2 collapses both into a single endpoint with filters:

• GET /api/public/v2/products?cityCode=...&categoryId=...
• GET /api/public/v2/products/{productId}

The product schema also got several field renames and one type change.

​

What to do

• Treat product IDs as opaque strings in V2. If you cast them to integers anywhere in your code, remove that cast.
• Rename your reads: images → media, ratingCumulative → reviewsSummary, and adjust the sub-field names.
• If you used startLocation.geolocation.latitude etc. in V1, the same data is now at the top level of the product.

​

Step 3 — Inventory

​

What changed

The endpoint moved and one parameter was renamed:

• V1: GET /api/public/v1/inventory/list-by/variant?variantId=...
• V2: GET /api/public/v2/inventory/list-by/tour?tourId=...

The response shape is largely preserved, with V2 additions (per-slot person types, paxRange, richer pricing).

​

What to do

• Swap the path and rename the parameter from variantId to tourId.
• Continue fetching inventory in real time before booking — that hasn’t changed.

​

Step 4 — Bookings

​

What changed

The path is now plural with a trailing slash:

• V1: POST /api/public/v1/booking, PUT /api/public/v1/booking/{id}, GET /api/public/v1/booking[/...]
• V2: POST /api/public/v2/bookings/, PUT /api/public/v2/bookings/{bookingId}/, GET /api/public/v2/bookings/, GET /api/public/v2/bookings/{bookingId}/

The capture flow itself is unchanged — Create → Update with status: "PENDING".

​

What to do

• Update the path. Nothing else in the booking creation flow needs to change.
• The status enum is identical, so any status-handling logic carries over.

​

Step 5 — Pricing

​

What changed

In V1, the pricing field on a product was a “from” listing price (minimum across variants). V2 redesigned this so there is a single, canonical pricing object:

• pricing (V2) — the object to read. Returns currency, profileType (PER_PERSON / PER_GROUP), headoutSellingPrice (MSP), and netPrice (the partner net price for API Partners).
• listingPrice (V2) — exists on the response for backward compatibility but is deprecated. Don’t use it in new code.

​

What to do

• Move pricing reads to V2 pricing. For variant-level pricing, use Get Product — V2 returns pricing inside each variant too.
• If you used pricing.minimumPrice in V1 to render a “from” price, the equivalent in V2 is the product-level pricing object.

See Pricing for the full model.

​

Step 6 — Adopt what’s new in V2

These don’t exist in V1 at all. You can adopt each independently after the basics are migrated.

• Webhooks (Create webhook). Replace polling Get Booking with push-based status updates. See Verifying webhook authenticity for the IP-whitelisting workaround.
• Cancel (Cancel booking). First-class endpoint. Refund handling is separate from cancellation eligibility — see Cancellation & reschedule policies.
• Reschedule (Reschedule booking). Synchronous acknowledgement plus asynchronous fulfilment.
• Seatmap (Seatmap availabilities, Inventory, Validate, SVG, Iframe). Seat-level theatre and live-entertainment products.

​

Running V1 and V2 side by side

Each step above is independent. You can migrate one resource at a time — for example, switch product reads to V2 while leaving bookings on V1 — and roll forward when each piece is verified. There is no requirement to flip everything at once.