Pick-up time vs Flight departure time

When booking transfers via the API, the way you provide the flight/pickup time reference depends on how your agency account is configured.
There are two different modes:

Flight (or Ship/Train) departure time based (System calculates pickup time)
Pick-up time based (You specify exact pickup time)

Understanding the difference is important to avoid errors or passengers missing their transfers.

🔹 Flight departure time based (default)

Instead of telling us when to pick up the passengers, you provide the arrival/departure time of their flight/ship/train.
Our system automatically calculates the best pick-up time based on:
- Distance to the arrival/departure point
- Service rules (e.g. check-in windows, required arrival buffer at airports)

Key points

Use the field flight_date_time, ship_date_time, or train_date_time depending on the type of service.
The pick-up time is not required in your request – it will be calculated automatically..

Example:

{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
    }
  },
  "destination": {
    "flight": {
      "airline_code": "RYR",
      "flight_number": "3256",
      "airport_code": "BCN",
      "flight_date_time": "2025-09-03T15:35:00"
    }
  }
}

{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
    }
  },
  "destination": {
    "train": {
      "train_number": "FRT-345",
      "train_date_time": "2025-09-03T15:35:00"
    }
  }
}

{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
    }
  },
  "destination": {
    "cruise": {
      "cruise_line": "Carnival Cruise Line",
      "ship_name": "A-Rosa Aqua",
      "cruise_terminal": "TERMINAL-1",
      "ship_date_time": "2025-09-03T15:35:00"
    }
  }
}

📘
Special feature for Flight departure time based accounts
Pick-up time override — private vehicles only
Even if your account is Flight departure time based, you may explicitly set the pick-up time for private vehicles by including pickup_date_time together with the relevant departure time field.
Rules

✅ Allowed only for private transfers with destination to gateways

❌ Not allowed for shuttles (shared services).

Required fields in the same request:

pickup_date_time (your exact desired pick-up time)

flight_date_time / ship_date_time / train_date_time (kept for validation, routing, and comms)

Responsibility: when you override pick-up time, you must ensure sufficient buffer for check-in/security.

Example
{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
      "pickup_date_time": "2025-09-03T13:15:00"
    }
  },
  "destination": {
    "flight": {
      "airline_code": "RYR",
      "flight_number": "3256",
      "airport_code": "BCN",
      "flight_date_time": "2025-09-03T15:35:00"
    }
  }
}
{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
      "pickup_date_time": "2025-09-03T13:15:00"
    }
  },
  "destination": {
    "train": {
      "train_number": "FRT-345",
      "train_date_time": "2025-09-03T15:35:00"
    }
  }
}
{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
      "pickup_date_time": "2025-09-03T13:15:00"
    }
  },
  "destination": {
    "cruise": {
      "cruise_line": "Carnival Cruise Line",
      "ship_name": "A-Rosa Aqua",
      "cruise_terminal": "TERMINAL-1",
      "ship_date_time": "2025-09-03T15:35:00"
    }
  }
}

🔹 Pick-up time based

Optional configuration that must be requested through our B2B commercial team before use.
In this case, agencies must provide the exact pick-up date and time (pickup_date_time) in the request.
The driver will be scheduled to arrive at the exact time provided.
No automatic calculation of pick-up time is done by the system.

Example

{
  "outward": {
    "accommodation": {
      "address": "Carrer Marquès de Barberà, 22",
      "pickup_date_time": "2025-09-03T15:35:00"
    }
  },
  "destination": {
    "flight": {
      "airline_code": "RYR",
      "flight_number": "3256",
      "airport_code": "BCN"
    }
  }
}

🚧
Shuttle to a gateway (airport/port/station)
Even when your account is pick‑up time based, if you are booking a shuttle vehicle and the destination is a gateway (airport, port or train station), you must always also provide the departure date/time for the gateway service:

Send pickup_date_time and the corresponding flight_date_time / ship_date_time / train_date_time.

Rationale: shared services require a verified departure time to allocate routeing and arrival buffers.

Example (pick‑up based + shuttle to airport — both values required)
{
  "outward": {
    "accommodation": {
      "name": "Hotel Barbarà",
      "address": "Carrer Marquès de Barberà, 22",
      "pickup_date_time": "2025-09-03T14:05:00"
    }
  },
  "destination": {
    "flight": {
      "airline_code": "RYR",
      "flight_number": "3256",
      "airport_code": "BCN",
      "flight_date_time": "2025-09-03T18:35:00"
    }
  }
}

Summary

Agencies can configure transfers using either flight/ship/train departure time (default) or exact pick-up time (on request).
In departure time-based mode, only the departure time is needed; the system calculates the optimal pick-up time.
A manual override for pick-up time is allowed for private transfers in departure time-based mode, but both pick-up and departure times must be provided.
In pick-up time-based mode, agencies must supply the exact pick-up time; no automatic calculation is done.
For shuttles to gateways, even in pick-up time-based mode, the departure time is always required to ensure proper routing.

If you are unsure which mode your agency account uses, please check with your Suntransfers B2B commercial contact.

🔹 Flight departure time based (default)

Special feature for Flight departure time based accounts

🔹 Pick-up time based

Shuttle to a gateway (airport/port/station)

Summary