Pickups (Proposed Draft)
Adds hotel pickup functionality to the API
To use this capability, add octo/pickups
to your Octo-Capabilities
header.
Hotel pickup is sometimes offered by products where the guest can opt to be picked up from a different location instead of where the general meeting location is.
Product Pickups
GET
{host}/products/:id
Returns top-level pickup information on each product.
Path Parameters
id
string
The product id, leave this out to get every product.
Query Parameters
pickupRequested
boolean
Whether pickup was requested by the customer. May alter the pricing.
With this capability enabled, the supplier system will add pickupAvailable
pickupRequired
and pickupLocations
to each product. A sample of just these changes are:
{
//...rest of the product object
"pickupAvailable": true,
"pickupRequired": true,
"pickupLocations": [
{
"id": "0274665c-f047-42bd-a971-f31fcff24862",
"title": "Cornell Hotel de France - 715 Bush St",
"shortDescription": "Meet in front of the main lobby entrance",
"place": {
"latitude": 37.7900142,
"longitude": -122.4091263,
"postalAddress": {
"streetAddress": "715 Bush Street",
"addressLocality": "San Francisco",
"addressRegion": "California",
"postalCode": "94108",
"addressCountry": "US",
"postOfficeBoxNumber": null
},
"identifiers": [
{
"googlePlaceId": "ChIJs6F3JYyAhYARDiVdBrmivCs"
}
],
"sameAs": [
"https://www.cornellhotel.com",
"https://maps.google.com/?q=715+Bush+St+San+Francisco"
]
}
},
{
"id": "02f44fe5-c1e1-4173-b557-2f23c68e53ab",
"title": "SF Plaza Hotel - 510 Bush St",
"shortDescription": "Await guide in the lobby",
"place": {
"latitude": 37.7906443,
"longitude": -122.4058728,
"postalAddress": {
"streetAddress": "510 Bush Street",
"addressLocality": "San Francisco",
"addressRegion": "California",
"postalCode": "94108",
"addressCountry": "US",
"postOfficeBoxNumber": null
},
"identifiers": [
{
"googlePlaceId": "ChIJfyuv4YuAhYAR3MOypx9cg3Q"
}
],
"sameAs": [
"https://www.sfplazahotel.com",
"https://maps.google.com/?q=510+Bush+St+San+Francisco"
]
}
},
{
"id": "07a1f50c-da65-4a82-9799-676c58946d15",
"title": "Hilton Financial District - 750 Kearny St",
"shortDescription": "Meet at Hilton Financial District at 750 Kearny St.",
"place": {
"latitude": 37.7952284,
"longitude": -122.4040729,
"postalAddress": {
"streetAddress": "750 Kearny Street",
"addressLocality": "San Francisco",
"addressRegion": "California",
"postalCode": "94108",
"addressCountry": "US",
"postOfficeBoxNumber": null
},
"identifiers": [
{
"googlePlaceId": "ChIJOzt_KIuAhYARNdt9T_gCmKQ"
}
],
"sameAs": [
"https://www.hilton.com/en/hotels/sfofdhf-hilton-san-francisco-financial-district/",
"https://maps.google.com/?q=750+Kearny+St+San+Francisco"
]
}
}
]
}
pickupAvailable
Whether pickup is available for this product.
pickupRequired
If true, then a pickup location must be supplied during booking. Otherwise, it's optional whether the customer wants to be picked up or not.
pickupLocations
This is a list of all the possible pickup locations. Use this list for mapping purposes (if necessary) not all these pickup locations are available for every departure. To learn which ones are available, check the pickup availability below.
Paid Pickups
If using the octo/pricing
capability, the reseller system should add pickupRequested=true
to the product request, and the supplier system can quote the pricing with pickup. Setting it tofalse
will show you the pricing without.
Pickup Check
POST
{host}/availability
Returns a list of pickups for each departure.
Request Body
pickupRequested
boolean
Whether the customer requested pickup
pickupLocationId
string
The pickup location id selected
In the availability response we add pickupAvailable
pickupRequired
and pickupLocations
to each product. A sample of just these changes are:
[
{
"id": "2025-12-01T05:40:00-08:00",
"localDateTimeStart": "2025-12-01T05:40:00-08:00",
"localDateTimeEnd": "2025-12-03T05:40:00-08:00",
"utcCutoffAt": "2025-12-01T13:40:00Z",
"allDay": false,
"status": "AVAILABLE",
"vacancies": 56,
"capacity": null,
"maxUnits": null,
"openingHours": [],
"pickupAvailable": true,
"pickupRequired": true,
"pickupLocations": [
{
"id": "b54c6f8a-aacf-49b0-a6cf-ffabbe281936",
"title": "Bay Bridge Inn - 966 Harrison St",
"shortDescription": "Meet in front of the main lobby entrance",
"place": {
"latitude": 37.7779816,
"longitude": -122.4034593,
"postalAddress": {
"streetAddress": "966 Harrison Street",
"addressLocality": "San Francisco",
"addressRegion": "California",
"postalCode": "94107",
"addressCountry": "US",
"postOfficeBoxNumber": null
},
"identifiers": [
{
"googlePlaceId": "ChIJ3ZHXO4CAhYAR_yXRqYTfADU"
}
],
"sameAs": [
"https://www.baybridgeinn.com",
"https://maps.google.com/?q=966+Harrison+St+San+Francisco"
]
}
},
{
"id": "90e64d28-902f-4630-9932-5f0fb46992aa",
"title": "Americania Hotel - 121 7th St",
"shortDescription": "Meet at Americania Hotel - 121 7th St.",
"place": {
"latitude": 37.7788005,
"longitude": -122.4102065,
"postalAddress": {
"streetAddress": "121 7th Street",
"addressLocality": "San Francisco",
"addressRegion": "California",
"postalCode": "94103",
"addressCountry": "US",
"postOfficeBoxNumber": null
},
"identifiers": [
{
"googlePlaceId": "ChIJOTbxc4OAhYARrK82JwxWZFY"
}
],
"sameAs": [
"https://www.americaniahotel.com",
"https://maps.google.com/?q=121+7th+St+San+Francisco"
]
}
}
]
}
]
If you're using the octo/pricing
capability you should add pickupRequested=true
to any pricing request and it will quote you the pricing with pickup. Setting it to false
will show you the pricing without.
Booking Reservation
POST
https://{host}/octo/bookings
Adding pickup information to the booking request
Request Body
pickupRequested
boolean
Whether the customer requested pickup
pickupLocationId
string
The id of the chosen pickup location
pickupHotel
string
The hotel address (optional)
pickupHotelRoom
string
The hotel room number (optional)
{
"id": "2025-12-01T05:40:00-08:00",
"localDateTimeStart": "2025-12-01T05:40:00-08:00",
"localDateTimeEnd": "2025-12-03T05:40:00-08:00",
"utcCutoffAt": "2025-12-01T13:40:00Z",
"allDay": false,
"status": "AVAILABLE",
"vacancies": 56,
"capacity": null,
"maxUnits": null,
"openingHours": [],
"pickupAvailable": true,
"pickupRequired": true,
"pickupLocationId": "90e64d28-902f-4630-9932-5f0fb46992aa",
"pickupLocation": {
"id": "90e64d28-902f-4630-9932-5f0fb46992aa",
"title": "Americania Hotel - 121 7th St",
"shortDescription": "A modern boutique hotel with retro decor, conveniently located in San Francisco's SoMa district. Meet next to the parking lot entrance.",
"place": {
"latitude": 37.7788005,
"longitude": -122.4102065,
"postalAddress": {
"streetAddress": "121 7th Street",
"addressLocality": "San Francisco",
"addressRegion": "California",
"postalCode": "94103",
"addressCountry": "US"
},
"identifiers": [
{
"googlePlaceId": "ChIJOTbxc4OAhYARrK82JwxWZFY"
}
],
"sameAs": [
"https://www.americaniahotel.com",
"https://maps.google.com/?q=121+7th+St+San+Francisco"
]
}
}
}
The reseller system can also add these parameters to the booking confirmation request if you collect this data at a later stage.
An example request body will be like:
{
"pickupRequested": true,
"pickupLocationId": "90e64d28-902f-4630-9932-5f0fb46992aa"
}
Note if you do not have the ability to list the available pickup locations, but you do know the hotel which the customer is staying and want to request pickup you can make the request with the pickupHotel
field instead:
{
"pickupRequested": true,
"pickupHotel": "Americania Hotel - 121 7th St, San Francisco, US",
"pickupHotelRoom": "101"
}
The pickupHotelRoom
field is optional, but gives the guest the ability to specify their hotel room in case they are late and can be contacted.
The response will be the booking object with two extra fields: pickupRequested
and pickupLocation
. The result looks like this:
{
//..rest of the booking object
"pickupRequested": true,
"pickupLocationId": "90e64d28-902f-4630-9932-5f0fb46992aa",
"pickupHotel": "Americania Hotel - 121 7th St, San Francisco, US",
"pickupLocation": {
"id": "90e64d28-902f-4630-9932-5f0fb46992aa",
"title": "Americania Hotel - 121 7th St",
"shortDescription": "A modern boutique hotel with retro decor, conveniently located in San Francisco's SoMa district. Meet next to the parking lot entrance.",
"place": {
"latitude": 37.7788005,
"longitude": -122.4102065,
"postalAddress": {
"streetAddress": "121 7th Street",
"addressLocality": "San Francisco",
"addressRegion": "California",
"postalCode": "94103",
"addressCountry": "US"
},
"identifiers": [
{
"googlePlaceId": "ChIJOTbxc4OAhYARrK82JwxWZFY"
}
],
"sameAs": [
"https://www.americaniahotel.com",
"https://maps.google.com/?q=121+7th+St+San+Francisco"
]
}
}
}
Last updated
Was this helpful?