Packages

Adds package information showing sub-products within a booking

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

Packages are when a product contains multiple sub-products. Generally it's fine to sell packages without needing this capability, but using it will expose more information about the sub-products and allows you to customise the travel date of them.

Get Package Includes

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

The product schema has been updated to introduce two new fields:

product.isPackage which is a boolean field indicating whether this product is a package and therefore contains sub-products.

option.packageIncludes a list of the sub-products in groups on the option level.

For example:

{
  //... rest of the product object
  "isPackage": true,
  "options": [
    {
      //... rest of the option object
      "packageIncludes": [
        {
          "title": "Premium Products",
          "count": 1,
          "includes": [
            {
              "id": "b5e5721c-abab-4ed4-9e3a-721835549f20",
              "required": false,
              "limit": 1,
              "productId": "de1b3b5e-b8a0-4b4b-942f-283ebd9564ec",
              "product": {
                "id": "de1b3b5e-b8a0-4b4b-942f-283ebd9564ec",
                "internalName": "My Premium Attraction"
                //... full product object
              },
              "optionId": "5633bb77-934a-490f-ac2f-47a89f5ab349",
              "option": {
                "id": "5633bb77-934a-490f-ac2f-47a89f5ab349",
                "internalName": "Fast Track Entrance"
                //... full option object
              }
            }
            //... etc
          ]
        },
        {
          "title": "Standard Products",
          "count": 5,
          "includes": [
            {
              "id": "5b58af7f-3e8f-4fb7-b03c-b740a7164325",
              "required": false,
              "limit": 1,
              "productId": "d8759d3d-5d45-4bab-ba75-bd2715b712e7",
              "product": {
                "id": "d8759d3d-5d45-4bab-ba75-bd2715b712e7",
                "internalName": "My Walking Tour"
                //... full product object
              },
              "optionId": "8c680278-b3a3-4aa3-872a-1b23aea9a2d3",
              "option": {
                "id": "8c680278-b3a3-4aa3-872a-1b23aea9a2d3",
                "internalName": "Without Lunch"
                //... full option object
              }
            }
            //... etc
          ]
        }
      ]
    }
  ]
}

In the example above we have two include groups Premium Products and Standard Products this package is configured to allow you to pick 1 premium product and 5 standard products from the includes list.

The field definitions on the include object are as follows:

Field	Description
title	The name of the include group.
count	How many includes can be chosen from this group. Note the same include can be chosen multiple times if limit permits.
includes[]	A list of includes to choose from.
includes[].id	The packageIncludeId that must be used in future operations involving this include. More on this below.
includes[].required	Whether this include MUST be chosen, and will automatically count as one of your allowed includes.
includes[].limit	How many times this include can be picked. It's possible to pick the same include multiple times if limit is greater than 1, up to the total limit set by count.
includes[].productId	The id of the product this include represents.
includes[].product	The full product object included for your convenience.
includes[].optionId	The id of the option this include represents.
includes[].option	The full option object included for your convenience.

Now we need to book the inclusions.

Package Booking

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

It's possible to pick your includes before and after the booking is created. The process for doing so is identical and in this example we do it on the booking reservation call just as an example:

{
  "productId": "34639ddc-e4c6-4ba6-800c-bd2e4778e1e4",
  "optionId": "003986f6-97f4-4baa-8c54-2d09e5d0904e",
  "unitItems": [
    {
      "unitId": "unit_faef4e3a-6ff4-454a-adf8-19c6f1957fa2"
    }
  ],
  "packageBookings": [
    {
      "packageIncludeId": "b5e5721c-abab-4ed4-9e3a-721835549f20",
      "availabilityId": "2022-08-30"
    },
    {
      "packageIncludeId": "5b58af7f-3e8f-4fb7-b03c-b740a7164325",
      "availabilityId": "2022-08-32"
    }
  ]
}

In this example we make the booking reservation call for the package and include the inclusions we want to choose by putting them in the packageBookings array.

It might not look it buch each object under packageBookings is actually a full booking object, and will include all the fields you would otherwise include when making a booking (including for capabilities like custom questions, extras, hotel pickup, etc.). The only difference is the fields productId optionId and unitItems which would normally be required are ignored, that's because the package booking knows the product and option from the packageIncludeId value and the unitItems are ALWAYS fixed to be the same as the unitItems of the parent booking.

That means by buying 2 adults and 1 child of the parent, you will be automatically including 2 adults and 1 child of each of the package bookings also.

Package Booking

PATCH https://api.ventrata.com/octo/bookings/:uuid

Path Parameters

Name	Type	Description
uuid*	String	The booking UUID

It's also possible to pick the included products after the booking has already been reserved or confirmed. This can be done just by including the packageBookings array with the includes you have chosen.

Unlike the unitItems array this will only add to the list of package bookings, so you can call it it multiple times and it'll add package bookings each time without deleting the list already in there. To remove existing package bookings you have to DELETE them.

{
  "packageBookings": [
    {
      "packageIncludeId": "b5e5721c-abab-4ed4-9e3a-721835549f20",
      "availabilityId": "2022-08-30"
    }
  ]
}

The response on both endpoints is the same, and will return the package booking object. This package booking contains all the included bookings that you have booked or which were required and booked automatically for you when the sale was made. For example:

{
  //... rest of the booking object
  "isPackage": true,
  "packageBookings": [
    {
      //... rest of the booking object
      "uuid":  "b6fcaa4a-ed85-4ea2-8273-be18e6558437",
      "packageIncludeId": "b5e5721c-abab-4ed4-9e3a-721835549f20",
      "packageInclude": {
        //... rest of the package include object
      }
    },
    {
      //... rest of the booking object
      "uuid":  "b6fcaa4a-ed85-4ea2-8273-be18e6558437",
      "packageIncludeId": "5b58af7f-3e8f-4fb7-b03c-b740a7164325",
      "packageInclude": {
        //... rest of the package include object
      }
    }
  ]
}

You can then fetch the references/barcodes on the individual packageBookings and give these as separate vouchers to the guests.

To update/cancel one of the package bookings you can perform a PATCH / DELETE request on the package booking using its uuid value just as you would any normal booking.