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 Products

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

List all the products available for sale

Query Parameters

NameTypeDescription

categoryId

string

The category id to filter the products by

destinationId

string

The destination id to filter the products by

[
  {
    "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": "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/offers",
        "revision": 1,
        "required": false,
        "dependencies": ["octo/pricing"]
      },
      {
        "id": "octo/card-payment",
        "revision": 1,
        "required": false,
        "dependencies": []
      }
    ],
    "options": [
      {
        "id": "DEFAULT",
        "default": true,
        "internalName": "DEFAULT",
        "reference": null,
        "restrictions": {
          "minUnits": 0,
          "maxUnits": null
        },
        "units": [
          {
            "id": "unit_123abcadult",
            "internalName": "Adult",
            "reference": "adult",
            "type": "ADULT",
            "restrictions": {
              "minAge": 18,
              "maxAge": 99,
              "idRequired": false,
              "minQuantity": null,
              "maxQuantity": null,
              "paxCount": 1,
              "accompaniedBy": []
            }
          },
          {
            "id": "unit_321abcchild",
            "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

settlementMethods

An array of settlement methods allowed for this product. Possible values are: DIRECT The payment is made in full by card direct to the supplier (will require cardPayments capability) VOUCHER The payment is collected by the reseller and the net rate will be invoiced for by the supplier later. WHOLESALE The net rate is paid up-front by card direct to the supplier (will require cardPayemnts capability) and the commission (retail - net) is collected by the reseller and as such no further payment or invoice is necessary. DEPOSIT The commission (retail - net) is collected by the reseller as a deposit and the net rate is paid by the guest when they arrive at the supplier. DEFERRED No payment is made up-front and the full amount must be paid by the guest when they arrive.

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)

minPaxCount and maxPaxCount are minimum/maximum of people that can be purchased in a single booking. In most cases, these will be the same as minUnits and maxUnits, except for cases with multi-people units (e.g. Family could be 1 unit, but 4 pax).

options[].availabilityLocalStartTimes

This will be an array of all possible start times that can be returned during availability. For example an all day attraction may just have a single value like ["00:00"] but a tour with multiple departure times may have:["09:00", "14:00", "17:00"]

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[].requiredContactFields[]

An array of the contact fields required to confirm a booking. These just apply to the lead traveller on the booking and not for every ticket. Possible values are:

  • firstName

  • lastName

  • emailAddress

  • phoneNumber

  • streetAddress

  • postalCode

  • country

  • notes

  • locales

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 OTHER

The "other" type typically is used for an add-on, e.g. Bottle of Champaign, and not an actual ticket.

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.

options[].units[].requiredContactFields[]

An array of the contact fields required to confirm a booking. These apply to every ticket. Possible values are:

  • firstName

  • lastName

  • emailAddress

  • phoneNumber

  • streetAddress

  • postalCode

  • country

  • notes

  • locales

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 Product

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

Get details on a specific product

Path Parameters

NameTypeDescription

:id

string

The product id

{
  "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": "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/offers",
      "revision": 1,
      "required": false,
      "dependencies": ["octo/pricing"]
    },
    {
      "id": "octo/card-payment",
      "revision": 1,
      "required": false,
      "dependencies": []
    }
  ],
  "options": [
    {
      "id": "DEFAULT",
      "default": true,
      "internalName": "DEFAULT",
      "reference": null,
      "restrictions": {
        "minUnits": 0,
        "maxUnits": null
      },
      "units": [
        {
          "id": "unit_123abcadult",
          "internalName": "Adult",
          "reference": "adult",
          "type": "ADULT",
          "restrictions": {
            "minAge": 18,
            "maxAge": 99,
            "idRequired": false,
            "minQuantity": null,
            "maxQuantity": null,
            "paxCount": 1,
            "accompaniedBy": []
          }
        },
        {
          "id": "unit_321abcchild",
          "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

Last updated