Pickups

Adds pickup and dropoff functionality to the API

To use this capability, add octo/pickups to your Octo-Capabilities header.

Hotel pickup is offered by some products where guests can be collected from a pickup point (or hotel) before departure and optionally dropped off afterwards.

Operations below use the /octo prefix.

Product Pickups

This capability extends product routes documented in Products:

• GET /products

• GET /products/{productId}

This capability adds pickup/dropoff fields to each options[] object in the product response.

Query Parameters

This capability does not add pickup/dropoff-specific query parameters to product routes.

Added Option Fields

Base product schema: Products.

pickupPoints and dropoffPoints on product options are configuration lists. Availability-level filtering/times are returned by /availability.

The same option-level fields are also returned on booking.option in booking responses.

Pickup Check

This capability extends availability routes documented in Availability:

• POST /availability

• POST /availability/batch

Returns pickup/dropoff details per departure.

This capability does not add top-level availability fields.

Added Availability Fields

Base availability schema: Availability.

In availability responses, dropoffPoints is empty when dropoff is unavailable or when the departure has no end time.

The same availability-level fields are also returned on booking.availability in booking responses for dated bookings.

Booking Reservation

The same pickup/dropoff request fields are supported by these booking write routes:

• POST /bookings

• PATCH /bookings/{uuid}

• POST /bookings/{uuid}/confirm

If both pickupPointId and pickupHotel are sent, pickupPointId takes precedence.

When pickupHotel is used, the API first tries to match an existing pickup by name. If none is found, it geocodes/creates a hotel record and links it to the booking.

Send null for pickupPointId, pickupHotel, pickupHotelRoom, pickupNotes, dropoffPointId, or dropoffNotes to clear existing values.

Base booking schema: Bookings.

Added Booking Response Fields

These are additive response fields on the base booking schema from Bookings.

The same booking response fields are present on booking read/cancel routes that return booking objects, including GET /octo/bookings, GET /octo/bookings/:uuid, POST /octo/bookings/:uuid/cancel, and POST /octo/bookings/:uuid/extend.

Pickup Point Object

Used by pickupPoints[] and pickupPoint.

Dropoff Point Object

Used by dropoffPoints[] and dropoffPoint.

localDateTime and localDateTimeTo are not included on product option dropoffPoints[]; they are added in availability and booking responses.

Schema Additions (JSON)

These are additive fragments showing only fields introduced by this capability.

Availability

{
  "// ...rest of availability object": "...",
  "pickupAvailable": true,
  "dropoffAvailable": true,
  "pickupRequired": true,
  "dropoffRequired": true,
  "pickupPoints": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Union Square Pickup",
      "localDateTime": "2026-05-14T08:30:00-04:00"
    }
  ],
  "dropoffPoints": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Union Square Pickup",
      "localDateTime": "2026-05-14T08:30:00-04:00"
    }
  ],
  "pickupDispatch": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "name": "Shuttle A",
    "phoneNumber": "[phone]"
  },
  "dropoffDispatch": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "name": "Shuttle A",
    "phoneNumber": "[phone]"
  }
}

AvailabilityBatchRow

{
  "// ...rest of availability batch row object": "...",
  "pickupAvailable": true,
  "dropoffAvailable": true,
  "pickupRequired": true,
  "dropoffRequired": true,
  "pickupPoints": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Union Square Pickup",
      "localDateTime": "2026-05-14T08:30:00-04:00"
    }
  ],
  "dropoffPoints": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Union Square Pickup",
      "localDateTime": "2026-05-14T08:30:00-04:00"
    }
  ],
  "pickupDispatch": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "name": "Shuttle A",
    "phoneNumber": "[phone]"
  },
  "dropoffDispatch": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "name": "Shuttle A",
    "phoneNumber": "[phone]"
  }
}

AvailabilityResourcesRequest

{
  "// ...rest of availability resources request object": "...",
  "pickupPointId": "pickup_union_square",
  "dropoffPointId": "dropoff_fishermans_wharf"
}

Booking

{
  "// ...rest of booking object": "...",
  "pickupPoint": {
    "id": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
    "title": "Summer Promotion",
    "description": "Morning departure with central pickup included.",
    "localDateTime": "2026-05-14",
    "localDateTimeTo": "2026-05-14",
    "latitude": 10.0,
    "longitude": 10.0,
    "address": "123 Main St, San Francisco, CA",
    "googlePlaceId": "google_place_id-example"
  },
  "dropoffPoint": {
    "id": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
    "title": "Summer Promotion",
    "description": "Morning departure with central pickup included.",
    "localDateTime": "2026-05-14",
    "localDateTimeTo": "2026-05-14",
    "latitude": 10.0,
    "longitude": 10.0,
    "address": "123 Main St, San Francisco, CA",
    "googlePlaceId": "google_place_id-example"
  },
  "pickupPointId": "pickup_union_square",
  "dropoffPointId": "dropoff_fishermans_wharf",
  "pickupHotel": "Hilton Union Square",
  "pickupHotelRoom": "1208",
  "pickupNotes": "Meet the guide by the hotel lobby.",
  "dropoffNotes": "Drop-off at Fisherman's Wharf.",
  "pickupDispatch": {
    "id": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
    "name": "Morning City Tour",
    "phoneNumber": "[phone]",
    "vehicle": "coach_12"
  },
  "dropoffDispatch": {
    "id": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
    "name": "Morning City Tour",
    "phoneNumber": "[phone]",
    "vehicle": "coach_12"
  }
}

BookingWriteRequest

{
  "// ...rest of booking write request object": "...",
  "pickupRequested": true,
  "pickupPointId": "pickup_union_square",
  "dropoffRequested": true,
  "dropoffPointId": "dropoff_fishermans_wharf",
  "pickupHotel": "Hilton Union Square",
  "pickupHotelRoom": "1208",
  "pickupNotes": "Meet the guide by the hotel lobby.",
  "dropoffNotes": "Drop-off at Fisherman's Wharf."
}

Option

{
  "// ...rest of option object": "...",
  "pickupAvailable": true,
  "dropoffAvailable": true,
  "pickupRequired": true,
  "dropoffRequired": true,
  "pickupPoints": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Union Square Pickup",
      "localDateTime": "2026-05-14T08:30:00-04:00"
    }
  ],
  "dropoffPoints": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Union Square Pickup",
      "localDateTime": "2026-05-14T08:30:00-04:00"
    }
  ]
}

PackageAvailability

{
  "// ...rest of package availability object": "...",
  "pickupAvailable": true,
  "dropoffAvailable": true,
  "pickupRequired": true,
  "dropoffRequired": true,
  "pickupPoints": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Union Square Pickup",
      "localDateTime": "2026-05-14T08:30:00-04:00"
    }
  ],
  "dropoffPoints": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Union Square Pickup",
      "localDateTime": "2026-05-14T08:30:00-04:00"
    }
  ],
  "pickupDispatch": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "name": "Shuttle A",
    "phoneNumber": "[phone]"
  },
  "dropoffDispatch": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "name": "Shuttle A",
    "phoneNumber": "[phone]"
  }
}