# Transfers

This guide covers what is specific to transfers: the catalog, the availability calendar and the transfer item of a booking. The steps every product shares (the offer, the check, booking, reading, cancelling, the voucher and the errors) are in the [Booking flow](/developers/guides/v2-booking-flow) guide. Field-by-field detail is in the [Transfers reference](/developers/reference/v2/transfers) and the [Booking flow reference](/developers/reference/v2/bookings).

| Step | Call | What carries to the next step |
|---|---|---|
| 1 | `GET /api/v2/transfers/products` | `product_id` and `booking_requirements` |
| 2 | `POST /api/v2/transfers/availability` | `offer_id` |
| 3 | The [Booking flow](/developers/guides/v2-booking-flow) | |

## 1. List products

```bash
curl "https://highstartravel.com/api/v2/transfers/products" \
  -H "Authorization: Bearer YOUR_CREDENTIAL"
```

Each product has a `product_id`, `max_passengers` (adults plus children; infants do not count), `min_lead_days` and a `booking_requirements` object. A product your credential cannot sell is not listed.

`booking_requirements.travelers` tells you which traveler fields to collect. Transfers take only the lead traveler, the person the driver meets. `booking_requirements.logistics` has a `kind` (`airport_arrival`, `hotel`, `hotel_to_hotel`, `cruise` or `dual`) and the list of trip fields. Each field has `required`, and `required_when` for the `dual` kind. Keys that do not apply to the product are rejected with `VALIDATION_ERROR`.

The catalog changes rarely. The response has `Cache-Control: private, max-age=3600`.

## 2. Ask for availability

```bash
curl -X POST "https://highstartravel.com/api/v2/transfers/availability" \
  -H "Authorization: Bearer YOUR_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [301],
    "from": "2026-11-15",
    "to": "2026-11-22",
    "travelers": { "adult": 2, "child": 1, "infant": 0 }
  }'
```

The response has one entry in `results` per requested product, in request order:

```json
{
  "results": [
    {
      "product_id": 301,
      "currency": "USD",
      "days": [
        {
          "date": "2026-11-17",
          "availability": "available",
          "total": 120.0,
          "offer_id": "OFFER_ID_FROM_THIS_RESPONSE"
        }
      ]
    }
  ],
  "request_id": "3f8a9b7c1d2e4f5a6b7c8d9e0f1a2b3c"
}
```

- One call covers up to 20 products and 90 days. You get one offer per available day.
- `total` is the price of the whole group for that day, not per passenger. Holiday surcharges are included.
- Days that cannot be sold are left out: blocked days, days closer than `min_lead_days`, and days without a price for this group.
- If the group is bigger than the product's `max_passengers`, that product returns `days: []`. A group over 10 passengers fails the whole request with `VALIDATION_ERROR`.
- The offers carry no `expires_at`. The price is checked again when you book, and the check re-quotes it live. See the [Booking flow](/developers/guides/v2-booking-flow#1-the-offer).
- The response has `Cache-Control: private, max-age=300`.

## 3. The transfer item of a booking

The booking is the one described in the [Booking flow](/developers/guides/v2-booking-flow#3-book). A transfer item has these specifics:

```json
{
  "offer_id": "OFFER_ID",
  "travelers": [
    { "first_name": "John", "last_name": "Doe", "phone": "+15555550123", "nationality": "US" }
  ],
  "logistics": {
    "airport": "MCO",
    "airline": "AA",
    "flight_time": "13:45",
    "hotel": "Hotel name"
  }
}
```

- `travelers` has exactly one entry: the lead. The other passengers are counted in the offer and are not listed.
- `logistics` holds the keys that `booking_requirements.logistics` listed for the product. The example above is an `airport_arrival` product. `flight_time` is `HH:MM`, 24-hour, local to the airport.
- One item per booking today.
- The booking answer returns the lead in `lead_traveler` and the trip in `logistics`.

## Next

The rest is the [Booking flow](/developers/guides/v2-booking-flow) guide: the check, booking and retries, reading, cancelling and the voucher.