Products

Mapping the supplier available products and options to your reseller system.

Most reseller systems have a database of products. You will need to map to products returned in this API call.

The main components that you are required to map are: Product, Options, Units

The product ID, at least one option and units are required for inventory checks and booking calls. These are required for subsequent calls.

List Products

GET https://api.zaui.io/octo/suppliers/{id}/products/

Provides a list of all available products for resell provided by the supplier.

Path Parameters

NameTypeDescription

id*

string/uuid

The supplier ID

[
    {
        "id": "cabfc194-9443-40fa-8342-85ed9d8ec58c",
        "internalName": "11:00am - Wilderness Run",
        "reference": null,
        "locale": "en-US",
        "timeZone": "America/Vancouver",
        "allowFreesale": false,
        "availabilityRequired": true,
        "availabilityType": "START_TIME",
        "deliveryFormats": [
            "QRCODE"
        ],
        "deliveryMethods": [
            "VOUCHER",
            "TICKET"
        ],
        "redemptionMethod": "DIGITAL",
        "instantConfirmation": true,
        "instantDelivery": true,
        "options": [
            {
                "id": "DEFAULT",
                "default": true,
                "internalName": "Standard Tour 11:00:00",
                "reference": null,
                "restrictions": {
                    "minUnits": null,
                    "maxUnits": null
                },
                "availabilityLocalStartTimes": [
                    "11:00", "12:00"
                ],
                "requiredContactFields": [
                    "firstName",
                    "lastName"
                ],
                "cancellationCutoff": "0 hours",
                "cancellationCutoffAmount": 0,
                "cancellationCutoffUnit": "hour",
                "units": [
                    {
                        "id": "seniors_83af6d2c-1c35-4728-ac03-3418a75c5579",
                        "internalName": "SENIORS",
                        "reference": "Single Rider $239",
                        "type": "SENIORS",
                        "requiredContactFields": [
                            "firstName",
                            "lastName"
                        ],
                        "restrictions": {
                            "minAge": 0,
                            "maxAge": 99,
                            "idRequired": false,
                            "minQuantity": null,
                            "maxQuantity": null,
                            "paxCount": 1,
                            "accompaniedBy": [
                              "seniors_83af6d2c-1c35-4728-ac03-3418a75c5579"
                            ]
                        }
                    },
                    {
                        "id": "adults_0e064227-c793-426b-857c-2d1fcba62582",
                        "internalName": "ADULTS",
                        "reference": "Double Rider $239",
                        "type": "ADULTS",
                        "requiredContactFields": [
                            "firstName",
                            "lastName"
                        ],
                        "restrictions": {
                            "minAge": 0,
                            "maxAge": 99,
                            "idRequired": false,
                            "minQuantity": null,
                            "maxQuantity": null,
                            "paxCount": 1,
                            "accompaniedBy": [
                              "adults_0e064227-c793-426b-857c-2d1fcba62582"
                            ]
                        }
                    }
                ]
            }
        ]
    },
    //Many Product Objects
]

Response keys:

Field

Description

id

Product ID. You need to save this.

internalName

Product name used by the supplier.

reference

An optional code this supplier might use to identify the product.

locale

A language code indicating what language this product content is in (BCP 47 RFC 5646 RFC 4647 language tag).

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.

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 that 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

instantDelivery

This indicates whether the Reseller can expect immediate delivery of the customer's tickets. If false then the Reseller MUST be able to delay delivery of the tickets to the customer.

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

options

An array of all options for this product, this list will not be empty.

options[].id

The id that identifies this option and is only unique within the product.

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 have a single value like ["00:00"] whilst a tour with multiple departure times may have multiple:["09:00", "14:00", "17:00"].

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

Required Values: firstName, lastName

options[].restrictions

An object containing a fixed list of restrictions.

options[].restrictions.minUnits

The minimum number of tickets that can be purchased in a single booking (null = 0)

options[].restrictions.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.

options[].cancellationCutOffAmount

An integer representing the cut-off amount.

options[].cancellationCutOffUnit

The cut-off unit. Values: minute, hour or day.

options[].units

The list of ticket types (units) available for sale.

options[].units[].id

The id of the unit that is 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: SENIORS, ADULTS, STUDENTS, CHILDREN, INFANTS

options[].units[].requiredContactFields

This is the array of the contact information PER ticket that the supplier expects.

Required Values: firstName, lastName

options[].units[].restrictions

An object containing restrictions about this unit. Possible keys and values are:

options[].units[].restrictions.minAge

An integer indicating the minimum age for the person this unit is for.

options[].units[].restrictions.maxAge

An integer indicating the maximum age for the person this unit is for.

options[].units[].restrictions.idRequired

A Boolean value indicating whether the person this unit is for must show ID on arrival.

options[].units[].restrictions.minQuantity

The minimum quantity of this unit required per booking (null = no minimum)

options[].units[].restrictions.maxQuantity

The maximum quantity of this unit required per booking (null = no limit)

options[].units[].restrictions.paxCount

This is the amount of people each unit counts as (e.g. family == 4pax)

options[].units[].restrictions.accompaniedBy

An array of unit ids one of which must accompany this unit if it is purchased.

Get Product

GET https://api.zaui.io/octo/suppliers/{sid}/products/{id}

This endpoint will respond with a single product object.

Path Parameters

NameTypeDescription

sid*

string/uuid

The supplier ID

id*

string/uuid

The product ID

{
    "id": "cabfc194-9443-40fa-8342-85ed9d8ec58c",
    "internalName": "Vancouver Sightseeing Tour",
    "reference": null,
    "locale": "en-US",
    "timeZone": "America/Vancouver",
    "allowFreesale": true,
    "availabilityRequired": true,
    "availabilityType": "START_TIME",
    "deliveryFormats": [
        "QRCODE"
    ],
    "deliveryMethods": [
        "VOUCHER",
        "TICKET"
    ],
    "redemptionMethod": "DIGITAL",
    "instantConfirmation": true,
    "instantDelivery": true,
    "options": [
        {
            "id": "DEFAULT",
            "default": true,
            "internalName": "Standard Tour 16:00:00",
            "reference": null,
            "restrictions": {
                "minUnits": null,
                "maxUnits": null
            },
            "availabilityLocalStartTimes": [
                "10:00", "12:00"
            ],
            "requiredContactFields": [
                "firstName",
                "lastName"
            ],
            "cancellationCutoff": "0 hours",
            "cancellationCutoffAmount": 0,
            "cancellationCutoffUnit": "hour",
            "units": [
                {
                    "id": "adults_0e064227-c793-426b-857c-2d1fcba62582",
                    "internalName": "ADULTS",
                    "reference": "Adults",
                    "type": "ADULTS",
                    "requiredContactFields": [
                        "firstName",
                        "lastName"
                    ],
                    "restrictions": {
                        "minAge": 0,
                        "maxAge": 99,
                        "idRequired": false,
                        "minQuantity": null,
                        "maxQuantity": null,
                        "paxCount": 1,
                        "accompaniedBy": [
                          "adults_0e064227-c793-426b-857c-2d1fcba62582"
                        ]
                    }
                },
                {
                    "id": "students_53gf6t2c-1c35-4728-dc03-5328a75c5579",
                    "internalName": "STUDENTS",
                    "reference": "Students",
                    "type": "STUDENTS",
                    "requiredContactFields": [
                        "firstName",
                        "lastName"
                    ],
                    "restrictions": {
                        "minAge": 0,
                        "maxAge": 99,
                        "idRequired": false,
                        "minQuantity": null,
                        "maxQuantity": null,
                        "paxCount": 1,
                        "accompaniedBy": [
                          "students_53gf6t2c-1c35-4728-dc03-5328a75c5579"
                        ]
                    }
                },
                {
                    "id": "children_ea3b2ef2-a035-45d4-9a65-9f86b779f7df",
                    "internalName": "CHILDREN",
                    "reference": "Children",
                    "type": "CHILDREN",
                    "requiredContactFields": [
                        "firstName",
                        "lastName"
                    ],
                    "restrictions": {
                        "minAge": 0,
                        "maxAge": 99,
                        "idRequired": false,
                        "minQuantity": null,
                        "maxQuantity": null,
                        "paxCount": 1,
                        "accompaniedBy": [
                          "children_ea3b2ef2-a035-45d4-9a65-9f86b779f7df"
                        ]
                    }
                },
                {
                    "id": "infants_8acdc5fe-97ed-4f68-a2c3-84fe74b3e3e5",
                    "internalName": "INFANTS",
                    "reference": "Infants",
                    "type": "INFANTS",
                    "requiredContactFields": [
                        "firstName",
                        "lastName"
                    ],
                    "restrictions": {
                        "minAge": 0,
                        "maxAge": 99,
                        "idRequired": false,
                        "minQuantity": null,
                        "maxQuantity": null,
                        "paxCount": 1,
                        "accompaniedBy": [
                          "infants_8acdc5fe-97ed-4f68-a2c3-84fe74b3e3e5"
                        ]
                    }
                }
            ]
        }
    ]
}

Response from this endpoint is the same as GET /products/ except as a single Product object.

Last updated