Skip to main content
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:

​
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: The product schema also got several field renames and one type change.
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: 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: 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.

​
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.