Products

List available products for purchase

Either you have a database of products that you need to map to products returned in this API, or you choose to import the product list from this endpoint to your system.
Ventrata has also implemented a self-service mapping capability that substantially reduces the burden of maintaining mappings. We recommend you implement this if you are able to. Click here for the documentation.
get
List Products
https://api.ventrata.com/octo/products
List all the products available for sale
Request
Response
Request
Query Parameters
categoryId
optional
string
The category id to filter the products by
destinationId
optional
string
The destination id to filter the products by
Response
200: OK
[
  {
    "id": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
    "internalName": "Walking Tour of Barcelona",
    "reference": "BRC-WALK",
    "locale": "en",
    "timeZone": "Europe/Madrid",
    "allowFreesale": true,
    "availabilityType": "START_TIME",
    "deliveryFormats": ["PDF_URL", "QRCODE"],
    "deliveryMethods": ["TICKET", "VOUCHER"],
    "redemptionMethod": "DIGITAL",
    "capabilities": [
      {
        "id": "ventrata/content",
        "revision": 1,
        "required": false,
        "dependencies": []
      },
      {
        "id": "ventrata/cart",
        "revision": 1,
        "required": false,
        "dependencies": []
      },
      {
        "id": "ventrata/pricing",
        "revision": 1,
        "required": false,
        "dependencies": []
      },
      {
        "id": "ventrata/offers",
        "revision": 1,
        "required": false,
        "dependencies": ["ventrata/pricing"]
      },
      {
        "id": "ventrata/card-payment",
        "revision": 1,
        "required": false,
        "dependencies": []
      }
    ],
    "options": [
      {
        "id": "DEFAULT",
        "default": true,
        "internalName": "DEFAULT",
        "reference": null,
        "restrictions": {
          "minUnits": 0,
          "maxUnits": null
        },
        "units": [
          {
            "id": "adult",
            "internalName": "Adult",
            "reference": "adult",
            "type": "ADULT",
            "restrictions": {
              "minAge": 18,
              "maxAge": 99,
              "idRequired": false,
              "minQuantity": null,
              "maxQuantity": null,
              "paxCount": 1,
              "accompaniedBy": []
            }
          },
          {
            "id": "child",
            "internalName": "Child",
            "reference": "child",
            "type": "CHILD",
            "restrictions": {
              "minAge": 0,
              "maxAge": 17,
              "idRequired": false,
              "minQuantity": null,
              "maxQuantity": null,
              "paxCount": 1,
              "accompaniedBy": ["adult"]
            }
          }
        ]
      }
    ]
  }
  // ...rest of the products
]
A description of each of the keys is given below:
Field
Description
id
The product id, you'll need to save this.
internalName
The name this suppliers calls the product.
reference
An optional code this supplier might use to identify the product.
locale
A language code indicating what language this product content is in.
timeZone
The IANA TimeZone name this product is located in.
allowFreesale
Whether a booking can be made for this product without having to query availability first.
instantConfirmation
Whether bookings will be immediately confirmed when a sale is made, otherwise the supplier will later either accept or reject the booking.
availabilityRequired
Whether an availabilityId is required when creating a booking. Without this the booking will be open-dated and not have a specified travel date.
availabilityType
What type of availability this product has, possible values are:
START_TIME if there are fixed departure times which you must pick one. Typical for day tours or activities.
OPENING_HOURS if you just select a date and can visit any time when the venue is open.
deliveryFormats
An array of formats the API will deliver the tickets as. Possible values are:
QRCODE A code to be presented as a QR CODE barcode
CODE128A code to be presented as a CODE 128 barcode
PDF_URL A URL to a PDF file which contains all the ticket details
deliveryMethods
How the formats described in deliveryFormats will be delivered in the booking response, possible values are:
TICKET Individually per unit in the order (i.e. single ticket for each person)
VOUCHER One ticket for the whole booking
redemptionMethod
How must the guest present the ticket or voucher when they arrive at the venue. Possible values are:
MANIFEST The guest name will be written down and they just need to show up
DIGITAL The tickets/voucher must be scanned but can be on mobile
PRINT The tickets/voucher must be printed and presented on arrival
capabilities
Capabilities define API extensions that this product supports. Capabilities can be enabled using a special HTTP header that's described in the next section.
capabilities[].id
The capability id which identifies it
capabilities[].revision
An integer which will increment each time the specification for this capability is updated.
capabilities[].required
Whether this product cannot be sold without this capability being used.
capabilities[].dependencies
An array of other capability ids that this capability depends on.
capabilities[].docs
A url to the documentation for this capability is.
capabilities[].default
Whether this capability is enabled by default.
options
An array of all options for this product. All products must have at least one option.
options[].id
The id that identifies this option, it is only unique within the product
options[].default
If there is only one option this value is true to indicate it is the default and therefore doesn't need to be displayed.
options[].internalName
Like product internalName except for each option
options[].reference
Like product reference except for each option
options[].restrictions
An object containing a fixed list of restrictions. Keys and values are:
minUnits The minimum number of tickets that can be purchased in a single booking (null = 0)
maxUnits The maximum number of tickets that can be purchased in a single booking (null = unlimited)
options[].cancellationCutoff
This is how long before the tour the booking can be still be cancelled. We also provide booking.cancellable (boolean) which we recommend you use instead to know if the booking can be cancelled. e.g. (1 Hour)
options[].cancellationCutoffAmount
The numeric amount for the cutoff (e.g. 1)
options[].cancellationCutoffUnit
The cutoff unit (e.g. hour). Possible values are: minute hour day
options[].units
The list of ticket types (units) available for sale
options[].units[].id
The id of the unit, this will be unique to the option
options[].units[].internalName
Like product/option internalName but for units
options[].units[].reference
Like product/option reference but for units
options[].units[].type
This is the ticket type of the unit, values are:
ADULT YOUTH CHILD INFANT FAMILY SENIOR STUDENT MILITARY
options[].units[].restrictions
An object containing restrictions about this unit. Possible keys and values are:
minAge An integer indicating the minimum age for the person this unit is for.
maxAge An integer indicating the maximum age for the person this unit is for.
idRequired A boolean value indicating whether the person this unit is for must show ID on arrival.
minQuantity The minimum quantity of this unit required per booking (null = no minimum)
maxQuantity The maximum quantity of this unit required per booking (null = no limit)
paxCount The number of people this unit allows. Typically this is 1 but for a family ticket for example, it could be 4 or 5.
accompaniedBy An array of unit ids one of which must accompany this unit if it is purchased.
If your server wants to query specific information about a product at a later stage, either to refresh your inventory or check for updates, you can call the following endpoint:
get
Get Product
https://api.ventrata.com/octo/products/:id
Get details on a specific product
Request
Response
Request
Path Parameters
:id
required
string
The product id
Response
200: OK
{
  "id": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
  "internalName": "Walking Tour of Barcelona",
  "reference": "BRC-WALK",
  "locale": "en",
  "timeZone": "Europe/Madrid",
  "allowFreesale": true,
  "availabilityType": "START_TIME",
  "deliveryFormats": ["PDF_URL", "QRCODE"],
  "deliveryMethods": ["TICKET", "VOUCHER"],
  "redemptionMethod": "DIGITAL",
  "capabilities": [
    {
      "id": "ventrata/content",
      "revision": 1,
      "required": false,
      "dependencies": []
    },
    {
      "id": "ventrata/cart",
      "revision": 1,
      "required": false,
      "dependencies": []
    },
    {
      "id": "ventrata/pricing",
      "revision": 1,
      "required": false,
      "dependencies": []
    },
    {
      "id": "ventrata/offers",
      "revision": 1,
      "required": false,
      "dependencies": ["ventrata/pricing"]
    },
    {
      "id": "ventrata/card-payment",
      "revision": 1,
      "required": false,
      "dependencies": []
    }
  ],
  "options": [
    {
      "id": "DEFAULT",
      "default": true,
      "internalName": "DEFAULT",
      "reference": null,
      "restrictions": {
        "minUnits": 0,
        "maxUnits": null
      },
      "units": [
        {
          "id": "adult",
          "internalName": "Adult",
          "reference": "adult",
          "type": "ADULT",
          "restrictions": {
            "minAge": 18,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          }
        },
        {
          "id": "child",
          "internalName": "Child",
          "reference": "child",
          "type": "CHILD",
          "restrictions": {
            "minAge": 0,
            "maxAge": 17,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": ["adult"]
          }
        }
      ]
    }
  ]
}
A description of the fields is given above

Test Credentials

Headers

Last updated 7 days ago

Field	Description
`id`	The product id, you'll need to save this.
`internalName`	The name this suppliers calls the product.
`reference`	An optional code this supplier might use to identify the product.
`locale`	A language code indicating what language this product content is in.
`timeZone`	The IANA TimeZone name this product is located in.
`allowFreesale`	Whether a booking can be made for this product without having to query availability first.
`instantConfirmation`	Whether bookings will be immediately confirmed when a sale is made, otherwise the supplier will later either accept or reject the booking.
`availabilityRequired`	Whether an `availabilityId` is required when creating a booking. Without this the booking will be open-dated and not have a specified travel date.
`availabilityType`	What type of availability this product has, possible values are: `START_TIME` if there are fixed departure times which you must pick one. Typical for day tours or activities. `OPENING_HOURS` if you just select a date and can visit any time when the venue is open.
`deliveryFormats`	An array of formats the API will deliver the tickets as. Possible values are: `QRCODE` A code to be presented as a QR CODE barcode `CODE128`A code to be presented as a CODE 128 barcode `PDF_URL` A URL to a PDF file which contains all the ticket details
`deliveryMethods`	How the formats described in `deliveryFormats` will be delivered in the booking response, possible values are: `TICKET` Individually per unit in the order (i.e. single ticket for each person) `VOUCHER` One ticket for the whole booking
`redemptionMethod`	How must the guest present the ticket or voucher when they arrive at the venue. Possible values are: `MANIFEST` The guest name will be written down and they just need to show up `DIGITAL` The tickets/voucher must be scanned but can be on mobile `PRINT` The tickets/voucher must be printed and presented on arrival
`capabilities`	Capabilities define API extensions that this product supports. Capabilities can be enabled using a special HTTP header that's described in the next section.
`capabilities[].id`	The capability id which identifies it
`capabilities[].revision`	An integer which will increment each time the specification for this capability is updated.
`capabilities[].required`	Whether this product cannot be sold without this capability being used.
`capabilities[].dependencies`	An array of other capability ids that this capability depends on.
`capabilities[].docs`	A url to the documentation for this capability is.
`capabilities[].default`	Whether this capability is enabled by default.
`options`	An array of all options for this product. All products must have at least one option.
`options[].id`	The id that identifies this option, it is only unique within the product
`options[].default`	If there is only one option this value is `true` to indicate it is the default and therefore doesn't need to be displayed.
`options[].internalName`	Like product internalName except for each option
`options[].reference`	Like product reference except for each option
`options[].restrictions`	An object containing a fixed list of restrictions. Keys and values are: `minUnits` The minimum number of tickets that can be purchased in a single booking (null = 0) `maxUnits` The maximum number of tickets that can be purchased in a single booking (null = unlimited)
`options[].cancellationCutoff`	This is how long before the tour the booking can be still be cancelled. We also provide `booking.cancellable` (boolean) which we recommend you use instead to know if the booking can be cancelled. e.g. (1 Hour)
`options[].cancellationCutoffAmount`	The numeric amount for the cutoff (e.g. 1)
`options[].cancellationCutoffUnit`	The cutoff unit (e.g. hour). Possible values are: `minute` `hour` `day`
`options[].units`	The list of ticket types (units) available for sale
`options[].units[].id`	The id of the unit, this will be unique to the option
`options[].units[].internalName`	Like product/option internalName but for units
`options[].units[].reference`	Like product/option reference but for units
`options[].units[].type`	This is the ticket type of the unit, values are: `ADULT` `YOUTH` `CHILD` `INFANT` `FAMILY` `SENIOR` `STUDENT` `MILITARY`
`options[].units[].restrictions`	An object containing restrictions about this unit. Possible keys and values are: `minAge` An integer indicating the minimum age for the person this unit is for. `maxAge` An integer indicating the maximum age for the person this unit is for. `idRequired` A boolean value indicating whether the person this unit is for must show ID on arrival. `minQuantity` The minimum quantity of this unit required per booking (null = no minimum) `maxQuantity` The maximum quantity of this unit required per booking (null = no limit) `paxCount` The number of people this unit allows. Typically this is 1 but for a family ticket for example, it could be 4 or 5. `accompaniedBy` An array of unit ids one of which must accompany this unit if it is purchased.

Products

getList Products

getGet Product

get
List Products

get
Get Product