> ## Documentation Index
> Fetch the complete documentation index at: https://partner.headout.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from V1 to V2

> What changes between the V1 and V2 Partner APIs, and what to update in an existing integration.

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/`](https://partner.headout.com/docs/api-partner/v2/cities/list)
* [`GET /api/public/v2/categories`](https://partner.headout.com/docs/api-partner/v2/categories/list)
* [`GET /api/public/v2/collections`](https://partner.headout.com/docs/api-partner/v2/collections/list) — **new in V2.** Themed groupings like "Broadway Shows" or "Statue of Liberty."
* [`GET /api/public/v2/subcategories`](https://partner.headout.com/docs/api-partner/v2/subcategories/list) — **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=...`](https://partner.headout.com/docs/api-partner/v2/products/list)
* [`GET /api/public/v2/products/{productId}`](https://partner.headout.com/docs/api-partner/v2/products/get)

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

| What you were reading in V1 | What to read in V2 |
| - | - |
| `id` (integer) | `id` (string) |
| `images[]` | `media[]` |
| `ratingCumulative` | `reviewsSummary` |
| `ratingCumulative.avg` | `reviewsSummary.averageRating` |
| `ratingCumulative.count` | `reviewsSummary.ratingsCount` |
| `pricing` (listing/"from" shape) | `pricing` (canonical — see [Pricing](#step-5--pricing)) |
| Nested `startLocation` object | Flat `LocationDetails` on the product |
| `primaryCategory` | `primaryCollection` |

> [!WARNING]
>
> **`primaryCategory` in V1 is not `primaryCategory` in V2.**
>
> V1 `primaryCategory` is a curated, city-scoped grouping (e.g. "West End Shows", "Dubai Desert Safari Tours"). V2 renamed that field `primaryCollection` and introduced a separate `primaryCategory` for broad global taxonomy (e.g. "Adventure", "Attractions & Museums"). Map V1 `primaryCategory` → V2 `primaryCollection`.

### 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.
* Map V1 `primaryCategory` to V2 **`primaryCollection`** — see the warning above.
* 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=...`](https://partner.headout.com/docs/api-partner/v2/inventory/list-by-tour)

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/`](https://partner.headout.com/docs/api-partner/v2/bookings/create), [`PUT /api/public/v2/bookings/{bookingId}/`](https://partner.headout.com/docs/api-partner/v2/bookings/update), [`GET /api/public/v2/bookings/`](https://partner.headout.com/docs/api-partner/v2/bookings/list), [`GET /api/public/v2/bookings/{bookingId}/`](https://partner.headout.com/docs/api-partner/v2/bookings/get)

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](https://partner.headout.com/docs/guide/concepts/inventory-and-pricing.md#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](https://partner.headout.com/docs/api-partner/v2/webhooks/create.md)). Replace polling `Get Booking` with push-based status updates. See [Verifying webhook authenticity](https://partner.headout.com/docs/guide/concepts/webhooks.md#verifying-webhook-authenticity) for the IP-whitelisting workaround.
* **Cancel** ([Cancel booking](https://partner.headout.com/docs/api-partner/v2/bookings/cancel.md)). First-class endpoint. Refund handling is separate from cancellation eligibility — see [Cancellation & reschedule policies](https://partner.headout.com/docs/guide/concepts/cancellation-and-reschedule.md).
* **Reschedule** ([Reschedule booking](https://partner.headout.com/docs/api-partner/v2/bookings/reschedule.md)). Synchronous acknowledgement plus asynchronous fulfilment.
* **Seatmap** ([Seatmap availabilities](https://partner.headout.com/docs/api-partner/v2/seatmap/availabilities-by-variant.md), [Inventory](https://partner.headout.com/docs/api-partner/v2/seatmap/inventory.md), [Validate](https://partner.headout.com/docs/api-partner/v2/seatmap/validate.md), [SVG](https://partner.headout.com/docs/api-partner/v2/seatmap/svg.md), [Iframe](https://partner.headout.com/docs/api-partner/v2/seatmap/iframe.md)). 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.