Pickups

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 to where the general meeting point is.

Product Pickups

GET https://api.ventrata.com/octo/products/:id

Returns top level pickup information on each product.

Path Parameters

Name	Type	Description
id	string	The product id, leave this out to get every product.

Query Parameters

Name	Type	Description
pickupRequested	boolean	Whether pickup was requested by the customer. May alter the pricing.

200

{
  "id": "93c335bc-07b9-4f10-84e2-3df8f2daa257",
  "internalName": "Mega Pass",
  "reference": null,
  "locale": "en",
  "timeZone": "America/Los_Angeles",
  "allowFreesale": false,
  "availabilityRequired": true,
  "availabilityType": "OPENING_HOURS",
  "deliveryFormats": [
    "PDF_URL",
    "QRCODE"
  ],
  "deliveryMethods": [
    "VOUCHER",
    "TICKET"
  ],
  "redemptionMethod": "DIGITAL",
  "capabilities": [
    {
      "id": "octo/content",
      "revision": 1,
      "required": false,
      "dependencies": []
    },
    {
      "id": "octo/cart",
      "revision": 1,
      "required": false,
      "dependencies": []
    },
    {
      "id": "octo/pricing",
      "revision": 1,
      "required": false,
      "dependencies": []
    },
    {
      "id": "octo/pickups",
      "revision": 1,
      "required": false,
      "dependencies": []
    },
    {
      "id": "octo/offers",
      "revision": 1,
      "required": false,
      "dependencies": [
        "octo/pricing"
      ]
    },
    {
      "id": "octo/cardPayments",
      "revision": 1,
      "required": false,
      "dependencies": []
    }
  ],
  "options": [
    {
      "id": "6963c6a3-5d6a-4f15-924c-be2530589422",
      "default": false,
      "internalName": "Pick 3",
      "reference": null,
      "restrictions": {
        "minUnits": 0,
        "maxUnits": null
      },
      "units": [
        {
          "id": "adult",
          "internalName": "Adult",
          "reference": "adult",
          "type": "ADULT",
          "restrictions": {
            "minAge": 0,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          },
          "pricingFrom": [
            {
              "original": 7999,
              "retail": 7999,
              "net": null,
              "currency": "USD",
              "currencyPrecision": 2
            }
          ]
        },
        {
          "id": "child",
          "internalName": "Child",
          "reference": "child",
          "type": "CHILD",
          "restrictions": {
            "minAge": 0,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          },
          "pricingFrom": [
            {
              "original": 5999,
              "retail": 5999,
              "net": null,
              "currency": "USD",
              "currencyPrecision": 2
            }
          ]
        }
      ]
    },
    {
      "id": "f39bde2f-2cc0-48c1-b404-af68ce2370ae",
      "default": false,
      "internalName": "Pick 4",
      "reference": null,
      "restrictions": {
        "minUnits": 0,
        "maxUnits": null
      },
      "units": [
        {
          "id": "adult",
          "internalName": "Adult",
          "reference": "adult",
          "type": "ADULT",
          "restrictions": {
            "minAge": 0,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          },
          "pricingFrom": [
            {
              "original": 9999,
              "retail": 9999,
              "net": null,
              "currency": "USD",
              "currencyPrecision": 2
            }
          ]
        },
        {
          "id": "child",
          "internalName": "Child",
          "reference": "child",
          "type": "CHILD",
          "restrictions": {
            "minAge": 0,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          },
          "pricingFrom": [
            {
              "original": 7999,
              "retail": 7999,
              "net": null,
              "currency": "USD",
              "currencyPrecision": 2
            }
          ]
        }
      ]
    },
    {
      "id": "f996c316-7541-4cb4-a96f-4a6f08cea70a",
      "default": false,
      "internalName": "Pick 5",
      "reference": null,
      "restrictions": {
        "minUnits": 0,
        "maxUnits": null
      },
      "units": [
        {
          "id": "adult",
          "internalName": "Adult",
          "reference": "adult",
          "type": "ADULT",
          "restrictions": {
            "minAge": 0,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          },
          "pricingFrom": [
            {
              "original": 11499,
              "retail": 11499,
              "net": null,
              "currency": "USD",
              "currencyPrecision": 2
            }
          ]
        },
        {
          "id": "child",
          "internalName": "Child",
          "reference": "child",
          "type": "CHILD",
          "restrictions": {
            "minAge": 0,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          },
          "pricingFrom": [
            {
              "original": 9299,
              "retail": 9299,
              "net": null,
              "currency": "USD",
              "currencyPrecision": 2
            }
          ]
        }
      ]
    }
  ],
  "defaultCurrency": "USD",
  "availableCurrencies": [
    "USD"
  ],
  "pickupAvailable": true,
  "pickupRequired": true,
  "pickupPoints": [
    {
      "id": "0274665c-f047-42bd-a971-f31fcff24862",
      "name": "Cornell Hotel de France - 715 Bush St",
      "directions": null,
      "latitude": 37.7900142,
      "longitude": -122.4091263,
      "googlePlaceId": "ChIJs6F3JYyAhYARDiVdBrmivCs",
      "street": "715 Bush Street",
      "postal_code": "94108",
      "locality": "San Francisco",
      "region": "California",
      "state": "CA",
      "country": "US" 
    },
    {
      "id": "02f44fe5-c1e1-4173-b557-2f23c68e53ab",
      "name": "SF Plaza Hotel - 510 Bush St",
      "directions": null,
      "latitude": 37.7906443,
      "longitude": -122.4058728,
      "googlePlaceId": "ChIJfyuv4YuAhYAR3MOypx9cg3Q",
      "street": "510 Bush Street",
      "postal_code": "94108",
      "locality": "San Francisco",
      "region": "California",
      "state": "CA",
      "country": "US"
    },
    {
      "id": "07a1f50c-da65-4a82-9799-676c58946d15",
      "name": "Hilton Financial District - 750 Kearny St",
      "directions": "Meet at Hilton Fincial District at 750 Kearny St.",
      "latitude": 37.7952284,
      "longitude": -122.4040729,
      "googlePlaceId": "ChIJOzt_KIuAhYARNdt9T_gCmKQ",
      "street": "750 Kearny Street",
      "postal_code": "94108",
      "locality": "San Francisco",
      "region": "California",
      "state": "CA",
      "country": "US"
    }
  ]
}

With this capability enabled we'll add pickupAvailable pickupRequired and pickupPoints to each product. A sample of just these changes are:

{
  //...rest of the product object
  "pickupAvailable": true,
  "pickupRequired": true,
  "pickupPoints": [
    {
      "id": "0274665c-f047-42bd-a971-f31fcff24862",
      "name": "Cornell Hotel de France - 715 Bush St",
      "directions": null,
      "latitude": 37.7900142,
      "longitude": -122.4091263,
      "googlePlaceId": "ChIJs6F3JYyAhYARDiVdBrmivCs",
      "street": "715 Bush Street",
      "postal_code": "94108",
      "locality": "San Francisco",
      "region": "California",
      "state": "CA",
      "country": "US" 
    },
    {
      "id": "02f44fe5-c1e1-4173-b557-2f23c68e53ab",
      "name": "SF Plaza Hotel - 510 Bush St",
      "directions": null,
      "latitude": 37.7906443,
      "longitude": -122.4058728,
      "googlePlaceId": "ChIJfyuv4YuAhYAR3MOypx9cg3Q",
      "street": "510 Bush Street",
      "postal_code": "94108",
      "locality": "San Francisco",
      "region": "California",
      "state": "CA",
      "country": "US"
    },
    {
      "id": "07a1f50c-da65-4a82-9799-676c58946d15",
      "name": "Hilton Financial District - 750 Kearny St",
      "directions": "Meet at Hilton Fincial District at 750 Kearny St.",
      "latitude": 37.7952284,
      "longitude": -122.4040729,
      "googlePlaceId": "ChIJOzt_KIuAhYARNdt9T_gCmKQ",
      "street": "750 Kearny Street",
      "postal_code": "94108",
      "locality": "San Francisco",
      "region": "California",
      "state": "CA",
      "country": "US"
    }
  ]
}

Field	Definition
pickupAvailable	Whether pickup is available for this product.
pickupRequired	If true, then a pickup point must be supplied during booking. Otherwise it's optional whether the customer wants to be picked up or not.
pickupPoints	This is a list of all the possible pickup points. Use this list for mapping purposes (if necessary) not all these pickup points are available for every departure. To know which are, check the pickup availability below.

If you're using the octo/pricing capability you should add pickupRequested=true to the product request and it will quote you the pricing with pickup. Setting it tofalse will show you the pricing without.

Pickup Check

POST https://api.ventrata.com/octo/availability

Returns a list of pickups for each departure.

Request Body

Name	Type	Description
pickupRequested	boolean	Whether the customer requested pickup
pickupPointId	string	The pickup point id selected

200

[
  {
    "id": "2020-12-01T05:40:00-08:00",
    "localDateTimeStart": "2020-12-01T05:40:00-08:00",
    "localDateTimeEnd": "2020-12-03T05:40:00-08:00",
    "utcCutoffAt": "2020-12-01T13:40:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "vacancies": null,
    "capacity": null,
    "maxUnits": null,
    "openingHours": [],
    "pickupAvailable": true,
    "pickupRequired": true,
    "pickupPoints": [
      {
        "id": "b54c6f8a-aacf-49b0-a6cf-ffabbe281936",
        "name": "Bay Bridge Inn - 966 Harrison St",
        "directions": null,
        "latitude": 37.7779816,
        "longitude": -122.4034593,
        "localDateTime": "2020-12-01T05:35:00-08:00",
        "googlePlaceId": "ChIJ3ZHXO4CAhYAR_yXRqYTfADU",
        "street": "966 Harrison Street",
        "postal_code": "94107",
        "locality": "San Francisco",
        "region": "California",
        "state": "CA",
        "country": "US"
      },
      {
        "id": "90e64d28-902f-4630-9932-5f0fb46992aa",
        "name": "Americania Hotel - 121 7th St",
        "directions": "Meet at Americania Hotel - 121 7th St.",
        "latitude": 37.7788005,
        "longitude": -122.4102065,
        "localDateTime": "2020-12-01T05:40:00-08:00",
        "googlePlaceId": "ChIJOTbxc4OAhYARrK82JwxWZFY",
        "street": "121 7th Street",
        "postal_code": "94103",
        "locality": "San Francisco",
        "region": "California",
        "state": "CA",
        "country": "US"
      }
    ]
  }
]

In the availability response we add pickupAvailable pickupRequired and pickupPoints to each product. A sample of just these changes are:

[
  {
    "id": "2020-12-01T05:40:00-08:00",
    "localDateTimeStart": "2020-12-01T05:40:00-08:00",
    "localDateTimeEnd": "2020-12-03T05:40:00-08:00",
    "utcCutoffAt": "2020-12-01T13:40:00Z",
    "allDay": false,
    "status": "AVAILABLE",
    "vacancies": null,
    "capacity": null,
    "maxUnits": null,
    "openingHours": [],
    "pickupAvailable": true,
    "pickupRequired": true,
    "pickupPoints": [
      {
        "id": "b54c6f8a-aacf-49b0-a6cf-ffabbe281936",
        "name": "Bay Bridge Inn - 966 Harrison St",
        "directions": null,
        "latitude": 37.7779816,
        "longitude": -122.4034593,
        "localDateTime": "2020-12-01T05:35:00-08:00",
        "googlePlaceId": "ChIJ3ZHXO4CAhYAR_yXRqYTfADU",
        "street": "966 Harrison Street",
        "postal_code": "94107",
        "locality": "San Francisco",
        "region": "California",
        "state": "CA",
        "country": "US"
      },
      {
        "id": "90e64d28-902f-4630-9932-5f0fb46992aa",
        "name": "Americania Hotel - 121 7th St",
        "directions": "Meet at Americania Hotel - 121 7th St.",
        "latitude": 37.7788005,
        "longitude": -122.4102065,
        "localDateTime": "2020-12-01T05:40:00-08:00",
        "googlePlaceId": "ChIJOTbxc4OAhYARrK82JwxWZFY",
        "street": "121 7th Street",
        "postal_code": "94103",
        "locality": "San Francisco",
        "region": "California",
        "state": "CA",
        "country": "US"
      }
    ]
  }
]

The only difference from the pickup list provided on the product endpoint is the addition of localDateTime which is the pickup time for that pickup in the local time zone.

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://api.ventrata.com/octo/bookings

Adding pickup information to the booking request

Request Body

Name	Type	Description
pickupRequested	boolean	Whether the customer requested pickup
pickupPointId	string	The id of the chosen pickup point
pickupHotel	string	The hotel address (optional)
pickupHotelRoom	string	The hotel room number (optional)

200

{
  "uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2",
  "testMode": true,
  "resellerReference": null,
  "supplierReference": "X749G9",
  "status": "ON_HOLD",
  "utcExpiresAt": "2020-06-07T17:06:37Z",
  "utcConfirmedAt": null,
  "productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
  "optionId": "DEFAULT",
  "cancellable": true,
  "cancellation": null,
  "freesale": false,
  "notes": "optional notes on the booking",
  "availability": {
    "id": "2020-07-01T14:30:00-05:00",
    "localDateTimeStart": "2020-07-01T14:30:00-05:00",
    "localDateTimeEnd": "2020-07-02T02:30:00-05:00",
    "allDay": true,
    "openingHours": []
  },
  "contact": {
    "fullName": null,
    "emailAddress": null,
    "phoneNumber": null,
    "locales": [],
    "country": null
  },
  "deliveryMethods": [
    "VOUCHER",
    "TICKET"
  ],
  "voucher": {
    "redemptionMethod": "DIGITAL",
    "utcRedeemedAt": null,
    "deliveryOptions": []
  },
  "unitItems": [
    {
      "uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f",
      "resellerReference": null,
      "supplierReference": "408H44",
      "unitId": "child",
      "ticket": {
        "redemptionMethod": "DIGITAL",
        "utcRedeemedAt": null,
        "deliveryOptions": []
      }
    },
    {
      "uuid": "ec1e2622-1359-437b-83f8-15182759d605",
      "resellerReference": null,
      "supplierReference": "BSDYM4",
      "unitId": "adult",
      "ticket": {
        "redemptionMethod": "DIGITAL",
        "utcRedeemedAt": null,
        "deliveryOptions": []
      }
    },
    {
      "uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb",
      "resellerReference": null,
      "supplierReference": "E5K92G",
      "unitId": "adult",
      "ticket": {
        "redemptionMethod": "DIGITAL",
        "utcRedeemedAt": null,
        "deliveryOptions": []
      }
    }
  ],
  "pickupRequested": true,
  "pickupPoint": {
    "id": "90e64d28-902f-4630-9932-5f0fb46992aa",
    "name": "Americania Hotel - 121 7th St",
    "directions": "Meet at Americania Hotel - 121 7th St.",
    "latitude": 37.7788005,
    "longitude": -122.4102065,
    "localDateTime": "2020-12-01T05:40:00-08:00"
  }
}

You 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,
    "pickupPointId": "90e64d28-902f-4630-9932-5f0fb46992aa"
}

Note if you do not have the ability to list the available pickup points, 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.

Ventrata will then attempt to geolocate that address (so please try and make it as accurate as possible) and will match it to the nearest possible pickup location.

The response will be the booking object with two extra fields: pickupRequested and pickupPoint. The result looks like this:

{
  //..rest of the booking object
  "pickupRequested": true,
  "pickupPointId": "90e64d28-902f-4630-9932-5f0fb46992aa",
  "pickupHotel": "Americania Hotel - 121 7th St, San Francisco, US",
  "pickupHotelRoom": "101",
  "pickupPoint": {
    "id": "90e64d28-902f-4630-9932-5f0fb46992aa",
    "name": "Americania Hotel - 121 7th St",
    "directions": "Meet at Americania Hotel - 121 7th St.",
    "latitude": 37.7788005,
    "longitude": -122.4102065,
    "localDateTime": "2020-12-01T05:40:00-08:00",
    "googlePlaceId": "ChIJOTbxc4OAhYARrK82JwxWZFY",
    "street": "121 7th Street",
    "postal_code": "94103",
    "locality": "San Francisco",
    "region": "California",
    "state": "CA",
    "country": "US"
  }
}