# Dropoffs \[NEW]

### Business Context

Dropoff service is commonly offered for tours and activities. It allows customers to be returned to one of the designated locations, or even to a customer-defined point within a supported dropoff area, instead of being left at the main ending point.

This service may be included for free or offered at an additional cost.

The OCTO Dropoffs Capability allows:

* **Supplier systems** to indicate whether a product option supports dropoff, whether dropoff is required, and to provide structured dropoff locations and areas.
* **Reseller systems** to obtain dropoff data, display available choices to customers during the booking flow, pass the customer’s selected dropoff location when creating, confirming, or updating a booking, and leverage a capability-specific endpoint to validate dropoff availability based on a customer-defined point (e.g., latitude/longitude).

Identical functionality is also available for pickups through the [Pickups](https://docs.octo.travel/capabilities-optional/pickups-new), which mirrors dropoffs and provides structured or customer-defined start-of-tour collection options.

### Capability Summary

To enable this capability when supported by a supplier system’s OCTO API, the reseller system must include `dropoffs` in the `Octo-Capabilities` header of its requests to the supplier system.

Adding `dropoffs` to your `Octo-Capabilities` header will alter OCTO Core endpoint behavior as follows:

<table data-full-width="true"><thead><tr><th width="254.8671875" data-type="content-ref">Endpoint</th><th>Dropoffs Capability Enhancements to OCTO Core</th></tr></thead><tbody><tr><td><a href="../../octo-api-core/supplier#get-supplier">#get-supplier</a></td><td><em>No additional functionality.</em></td></tr><tr><td><a href="../../octo-api-core/products#get-product-list">#get-product-list</a></td><td><a href="#get-product-list-and-get-product-with-pickups">Response</a> payload includes, per product option, whether dropoff is available, required for booking, and a list of supported locations/areas with their details. </td></tr><tr><td><a href="../../octo-api-core/products#get-product">#get-product</a></td><td><a href="#get-product-list-and-get-product-with-pickups">Response</a> payload includes, per product option, whether dropoff is available, required for booking, and a list of supported locations/areas with their details. </td></tr><tr><td><a href="../../octo-api-core/availability#availability-calendar">#availability-calendar</a></td><td><a href="#post-availability-calendar-with-pickups">Request</a> can specify if the customer wants dropoff and the chosen location. <a href="#post-availability-calendar-with-pickups">Response</a> includes, per calendar day, whether dropoff is available, required, and the list of supported locations/areas with details. </td></tr><tr><td><a href="../../octo-api-core/availability#availability-check">#availability-check</a></td><td><a href="#post-availability-check-with-pickups">Request</a> can specify if the customer wants dropoff and the chosen location. <a href="#post-availability-check-with-pickups">Response</a> includes, per availability, whether dropoff is available, required, the list of supported locations/areas with details, including dropoff time window.</td></tr><tr><td><a href="../../octo-api-core/bookings#create-booking">#create-booking</a></td><td><a href="#post-create-booking-patch-update-booking-with-pickups">Request</a> can specify if the customer wants dropoff, the chosen location, as well as any dropoff notes for booking. <a href="#post-create-booking-patch-update-booking-with-pickups">Response</a> includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window. </td></tr><tr><td><a href="../../octo-api-core/bookings#extend-pending-booking-expiration">#extend-pending-booking-expiration</a></td><td><a href="#post-create-booking-patch-update-booking-with-pickups">Response</a> includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window. </td></tr><tr><td><a href="../../octo-api-core/bookings#confirm-booking">#confirm-booking</a></td><td><a href="#post-create-booking-patch-update-booking-with-pickups">Response</a> includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window. </td></tr><tr><td><a href="../../octo-api-core/bookings#cancel-booking">#cancel-booking</a></td><td><a href="#post-create-booking-patch-update-booking-with-pickups">Response</a> includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window. </td></tr><tr><td><a href="../../octo-api-core/bookings#update-booking">#update-booking</a></td><td><a href="#post-create-booking-patch-update-booking-with-pickups">Request</a> can specify if the customer wants dropoff, the chosen location, as well as any dropoff notes for booking. <a href="../../octo-api-core/bookings#update-booking">Response</a> includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window. </td></tr><tr><td><a href="../../octo-api-core/bookings#get-booking-list">#get-booking-list</a></td><td><a href="#post-create-booking-patch-update-booking-with-pickups">Response</a> includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window. </td></tr><tr><td><a href="../../octo-api-core/bookings#get-booking">#get-booking</a></td><td><a href="#post-create-booking-patch-update-booking-with-pickups">Response</a> includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window. </td></tr></tbody></table>

\
**GET Booking Dropoff Locations Endpoint**

Additionally, this capability provides a dedicated endpoint [GET Booking Dropoffs Locations](#get-booking-pickup-locations), which enables searching for dropoff locations based on a customer-defined latitude and longitude, and validates whether dropoff service is available at that exact location or recommends alternate dropoff locations.&#x20;

### Additional OCTO Core Parameters & Schemas

#### [**GET Product List**](https://docs.octo.travel/octo-api-core/products#get-product-list) **AND** [**GET Product**](https://docs.octo.travel/octo-api-core/products#get-product) **(with** `dropoffs`**)**

**Request Body:**

```json
{
// ...rest of the OPTION object
  "dropoffAvailable": true,
  "dropoffRequired": false,
  "dropoffLocations": [
    {
      "id": "c1b2a3d4-5e6f-7081-92a3-b4c5d6e7f801",
      "title": "Sagrada Família",
      "shortDescription": "Dropoff available near the Basílica de la Sagrada Família in Barcelona. Guests are dropped at the coach parking area on Carrer de la Marina.",
      "place": {
        "latitude": 41.4036,
        "longitude": 2.1744,
        "postalAddress": {
          "streetAddress": "Carrer de la Marina, 253",
          "addressLocality": "Barcelona",
          "addressRegion": "Catalunya",
          "postalCode": "08013",
          "addressCountry": "ES",
          "postOfficeBoxNumber": null
        },
        "identifiers": [
          { "googlePlaceId": "ChIJp2VwQ0-hpBIRsY0R5pY2W7E" },
          { "tripadvisorLocationId": "876543" }
        ],
        "sameAs": [
          "https://maps.google.com/?cid=11111111111111111111"
        ]
      }
    },
    {
      "id": "f9e8d7c6-b5a4-3210-98f7-e6d5c4b3a210",
      "title": "Plaça de Catalunya",
      "shortDescription": "Central Barcelona dropoff at Plaça de Catalunya. Guests meet at the bus bays on the south side of the square.",
      "place": {
        "latitude": 41.3870,
        "longitude": 2.1701,
        "postalAddress": {
          "streetAddress": "Plaça de Catalunya",
          "addressLocality": "Barcelona",
          "addressRegion": "Catalunya",
          "postalCode": "08002",
          "addressCountry": "ES",
          "postOfficeBoxNumber": null
        },
        "identifiers": [
          { "googlePlaceId": "ChIJD7fiBh9uQgwR7-8fITgxTmU" }
        ],
        "sameAs": [
          "https://maps.google.com/?cid=22222222222222222222"
        ]
      }
    }
  ],
  // Optional, just intended as a visual aid
  "dropoffAreas": [
    {
      "title": "Central Barcelona Zone",
      "shortDescription": "Dropoff available across central Barcelona, including Eixample, the Gothic Quarter, and the waterfront around Port Vell. Guests are dropped at approved coach stops within this zone.",
      "area": {
        "coordinates": [
          { "latitude": 41.3945, "longitude": 2.1682 },
          { "latitude": 41.3891, "longitude": 2.1830 },
          { "latitude": 41.3758, "longitude": 2.1820 },
          { "latitude": 41.3769, "longitude": 2.1635 },
          { "latitude": 41.3945, "longitude": 2.1682 } // end up where you start
        ],
        "identifiers": [
          { "googlePlaceId": "ChIJ5TCOcRaipBIRX9G6FFzC7m8" },
          { "tripadvisorLocationId": "654321" }
        ],
        "sameAs": [
          "https://maps.google.com/?cid=33333333333333333333",
          "https://www.tripadvisor.com/Attraction_Review-central-barcelona"
        ]
      }
    }
  ]
}

```

#### [**POST Availability Calendar**](https://docs.octo.travel/octo-api-core/availability#availability-calendar) **(with** `dropoffs`**)** &#x20;

**Request Body:**

```json
{
  // ... rest of the OCTO Core availability request body
  "dropoffRequested": true,
  "dropoffLocationId": "9f1a3c1e-6b28-4e2a-9c7e-32d5a3a1f45e"
}
```

<table data-full-width="true"><thead><tr><th width="184.6015625">Field</th><th width="125.7734375">Type</th><th width="141.08203125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>dropoffRequested</code></td><td>boolean</td><td>optional</td><td>Whether the customer requested dropoff. </td></tr><tr><td><code>dropoffLocationId</code></td><td>string</td><td>optional</td><td>The dropoff location ID selected by the customer (must match one of <code>dropoffLocations[].id</code>).</td></tr></tbody></table>

**Response Body:**&#x20;

```json
{
  // ...rest of the CALENDAR DAY object
  "dropoffAvailable": true,
  "dropoffRequired": false
}
```

<table data-full-width="true"><thead><tr><th width="184.6015625">Field</th><th width="125.7734375">Type</th><th width="141.08203125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>dropoffAvailable</code></td><td>boolean</td><td>required</td><td>Indicates whether dropoff service is offered for this date.</td></tr><tr><td><code>dropoffRequired</code></td><td>boolean</td><td>required</td><td>Indicates whether selecting a dropoff location is mandatory for booking.</td></tr></tbody></table>

#### [**POST Availability Check**](https://docs.octo.travel/octo-api-core/availability#post-availability) **(with** `dropoffs`**)** &#x20;

**Request Body:**

```json
{
// ... rest of the OCTO Core availability request body
  "dropoffRequested": true,
  "dropoffLocationId": null (optional, if dropoffLocation is requested up-front)
}

```

<table data-full-width="true"><thead><tr><th width="184.6015625">Field</th><th width="125.7734375">Type</th><th width="141.08203125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>dropoffRequested</code></td><td>boolean</td><td>optional</td><td>Whether the customer requested dropoff. </td></tr><tr><td><code>dropoffLocationId</code></td><td>string</td><td>optional</td><td>The dropoff location ID selected by the customer (must match one of <code>dropoffLocations[].id</code>).</td></tr></tbody></table>

**Response Body:**&#x20;

```json
{
// ...rest of the AVAILABILITY object
  // ...note addition of localDateTimeStart and localDateTimeEnd below 
  "dropoffAvailable": true,
  "dropoffRequired": false,
  "localDropoffDateTimeStart": null, (only set if dropoffLocationId is set)
  "localDropoffDateTimeEnd": null, (only set if dropoffLocationId is set)
}

```

<table data-full-width="true"><thead><tr><th>Field</th><th width="242.22265625">Type</th><th width="118.24609375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>localDropoffDateTimeStart</code></td><td>string (<a href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO 8601</a>, i.e. YYYY-MM-DD)</td><td>optional</td><td>Start of the dropoff time window in the local time zone of the dropoff location. Indicates the earliest time the customer can be collected. </td></tr><tr><td><code>localDropoffDateTimeEnd</code></td><td>string (<a href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO 8601</a>, i.e. YYYY-MM-DD)</td><td>optional</td><td>End of the dropoff time window in the local time zone of the dropoff location. Indicates the latest time the customer can be collected.</td></tr></tbody></table>

#### [**POST Create Booking**](https://docs.octo.travel/octo-api-core/bookings#create-booking) **/** [**PATCH Update Booking**](https://docs.octo.travel/octo-api-core/bookings#update-booking) **(with** `dropoffs`**)**&#x20;

**Request Body:**

```json
{
// ... rest of the OCTO Core CREATE BOOKING request body
  "dropoffRequested": true,
  "dropoffLocationId": "9f1a3c1e-6b28-4e2a-9c7e-32d5a3a1f45e"
  "dropoffNotes": "Blue door next to the bakery"
}
```

<table data-full-width="true"><thead><tr><th>Field</th><th width="158.88671875">Type</th><th width="126.9609375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>dropoffRequested</code></td><td>boolean</td><td>optional</td><td>Whether the customer requested dropoff. </td></tr><tr><td><code>dropoffLocationId</code></td><td>string</td><td>optional</td><td>The dropoff location ID selected by the customer (must match one of dropoffLocations[].id).</td></tr><tr><td><code>dropoffpNotes</code></td><td>string</td><td>optional</td><td>Free-text notes provided by the customer for dropoff (e.g., Airbnb directions, gate code, nearby landmark, hotel room, etc).</td></tr></tbody></table>

**Response Body:**

```json
// ...rest of the BOOKING object
{
  "dropoffRequested": true,
  "dropoffLocationId": "a3f9c2d1-7e45-4b89-91f2-5d6e7c8b9a10",
  "dropoffNotes": "Main entrance under the glass canopy",
  "localDropoffDateTimeStart": "2025-06-15T18:10:00+02:00",
  "localDropoffDateTimeEnd": "2025-06-15T18:25:00+02:00",
  "dropoffLocation": {
    "id": "a3f9c2d1-7e45-4b89-91f2-5d6e7c8b9a10",
    "title": "Hotel Colosseo View",
    "shortDescription": "Dropoff available at Hotel Colosseo View, a short walk from the Colosseum. Guests should wait at the coach bay in front of the main entrance on Via dei Fori Imperiali.",
    "place": {
      "latitude": 41.8910,
      "longitude": 12.4923,
      "postalAddress": {
        "streetAddress": "Via dei Fori Imperiali 12",
        "addressLocality": "Roma",
        "addressRegion": "Lazio",
        "postalCode": "00184",
        "addressCountry": "IT",
        "postOfficeBoxNumber": null
      },
      "identifiers": [
        { "googlePlaceId": "ChIJ0X31pIKJPxMRXkS7Gz5Q2f8" },
        { "tripadvisorLocationId": "789012" }
      ],
      "sameAs": [
        "https://maps.google.com/?cid=44444444444444444444"
      ]
    }
  }
}
```

### GET Booking Dropoff Locations

`GET` {host}/bookings/{uuid}/dropoffLocations?latitude={lat}\&longitude={lng}

**Query Parameters:**&#x20;

<table data-full-width="true"><thead><tr><th>Name</th><th>Type</th><th width="185.03515625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>latitude</code></td><td>number</td><td>required</td><td>Customer-defined latitude (WGS84).</td></tr><tr><td><code>longitude</code></td><td>number</td><td>required</td><td>Customer-defined longitude (WGS84).</td></tr></tbody></table>

When latitude and longitude are not provided, the supplier system should return the full list of dropoff locations.

When latitude and longitude *are* provided, the supplier system may choose to either:

* return the full list of dropoff locations in any order,
* return the full list ordered in a way that reflects the lat/lon query,
* return only a subset of locations that best match the passenger’s position, or
* generate a new, virtual dropoff location on the fly that corresponds to the provided coordinates and can be used for booking creation or updates.

Reseller systems must be prepared for scenarios where a dropoff location ID returned during availability or booking does not appear in the static list retrieved via the general `dropoffLocations` query for that product option.

**Response Body:**

```json
{
  "localDropoffDateTimeStart": "2025-09-14T14:20:00+01:00",
  "localDropoffDateTimeEnd": "2025-09-14T14:35:00+01:00",
  "dropoffLocation": {
    "id": "b72c4e81-9d3f-4a3c-8a6f-0e92c4b1d993",
    "title": "Paddington Station – Praed St Entrance",
    "shortDescription": "Dropoff at the main Praed Street entrance, next to the taxi rank.",
    "place": {
      "latitude": 51.5167,
      "longitude": -0.1761,
      "postalAddress": {
        "streetAddress": "Praed Street",
        "addressLocality": "London",
        "addressRegion": "England",
        "postalCode": "W2 1HB",
        "addressCountry": "UK"
      },
      "identifiers": [
        { "googlePlaceId": "ChIJ5wCQT3YPdkgR0b6l5LjxaQ8" }
      ],
      "sameAs": [
        "https://maps.google.com/?q=Paddington+Station+Praed+Street"
      ]
    }
  }
},
{
  "localDropoffDateTimeStart": "2025-09-14T14:50:00+01:00",
  "localDropoffDateTimeEnd": "2025-09-14T15:05:00+01:00",
  "dropoffLocation": {
    "id": "e19a873b-04c3-48cc-9cb0-78bbcf6c1f44",
    "title": "London Eye – Riverside Walk",
    "shortDescription": "Dropoff near the entrance queue area on Riverside Walk.",
    "place": {
      "latitude": 51.5033,
      "longitude": -0.1195,
      "postalAddress": {
        "streetAddress": "Riverside Walk",
        "addressLocality": "London",
        "addressRegion": "England",
        "postalCode": "SE1 7PB",
        "addressCountry": "UK"
      }
    }
  }
}
```