Overview

Introduction

In Short

The following requirements must be satisfied for an API request to be successful:

  • Successful authentication using an API key
  • Use of Accept header with a supported Media Type
  • Use of Accept-Language header with a supported language
  • Use of correct HTTP verb
  • Existing resource identified by the URL path

Please continue reading to get an in-depth explanation of all these requirements.

Rentals explanation

Main idea is to have bookable time slots which can be chained to each other and form continuous booking time slot.

Example

Mandator has bike resource which can be booked for 1 hour intervals.

/availabilities response:

[
    {
        "type": "rental",
        "availabilityItemId": "42964359120_rental_20161025120000_20161025120000",
        "availabilityRuleId": 42964359120,
        "latestBookingTime": "2016-10-25T11:36:00+0200",
        "merchant_id": "15873",
        "merchant": "demo",
        "language": "en",
        "defaultLanguage": "en",
        "activityId": 66794,
        "activityTitle": "Helen",
        "startDate": "2016-10-25",
        "startTime": "12:00:00",
        "endDate": "2016-10-25",
        "endTime": "13:00:00",
        "timezone": "Europe\/Berlin",
        "duration": "PT360S",
        "bookingNote": "Checkin time 12:00",
        "availableSeats": 100,
        "capacity": 100,
        "occupancy": 0,
        "occupancyPaid": 0,
        "isExclusive": false,
        "isActive": true,
        "sortingToken": "1477389600---1477389600---Checkin time 12:00",
        "remarks": null,
        "startsAt": "2016-10-25T12:00:00+0200",
        "categories": [
            {
                "id": 7801094,
                "name": "S - Bike Rental",
                "description": "",
                "availableSeats": null,
                "capacity": null,
                "occupancy": 0,
                "occupancyPaid": 0,
                "minSeats": 1,
                "maxSeats": 1,
                "isCustom": false,
                "price": {
                    "amount": 20,
                    "currency": "USD"
                }
            },
            {
                "id": 7802575,
                "name": "M - Bike Rental",
                "description": "",
                "availableSeats": null,
                "capacity": null,
                "occupancy": 0,
                "occupancyPaid": 0,
                "minSeats": 1,
                "maxSeats": 1,
                "isCustom": false,
                "price":{
                    "amount": 20,
                    "currency": "USD"
                }
            }
        ]
    },
    ...
]

Rentals chain

In order to build rental chains availability items should be grouped by availabilityRuleId.

Chain could be build for every rental item by checking startTime + duration is equal to next item startTime.

Every rental item has it's own chain.

If one item in the list do not match that criteria it starts new chain.

Chain can have one item only.

For example there is a list of 6 rental items, first 4 elements are following each other (are chainable), then options for these rentals are:

[
    {
        "type": "rental",
        "availabilityItemId": "42964359120_rental_20161025120000_20161025120000",
        "availabilityRuleId": 42964359120,
        "startDate": "2016-10-25",
        "startTime": "12:00:00",
        "duration": "PT360S"
        ...
    },
    {
        "type": "rental",
        "availabilityItemId": "42964359120_rental_20161025120000_20161025120000",
        "availabilityRuleId": 42964359120,
        "startDate": "2016-10-25",
        "startTime": "13:00:00",
        "duration": "PT360S"
        ...
    },
    {
        "type": "rental",
        "availabilityItemId": "42964359120_rental_20161025120000_20161025120000",
        "availabilityRuleId": 42964359120,
        "startDate": "2016-10-25",
        "startTime": "14:00:00",
        "duration": "PT360S"
        ...
    },
    {
        "type": "rental",
        "availabilityItemId": "42964359120_rental_20161025120000_20161025120000",
        "availabilityRuleId": 42964359120,
        "startDate": "2016-10-25",
        "startTime": "15:00:00",
        "duration": "PT360S"
        ...
    },
    {
        "type": "rental",
        "availabilityItemId": "42964359120_rental_20161025120000_20161025120000",
        "availabilityRuleId": 42964359120,
        "startDate": "2016-10-25",
        "startTime": "17:00:00",
        "duration": "PT360S"
        ...
    },
    {
        "type": "rental",
        "availabilityItemId": "42964359120_rental_20161025120000_20161025120000",
        "availabilityRuleId": 42964359120,
        "startDate": "2016-10-25",
        "startTime": "19:00:00",
        "duration": "PT360S"
        ...
    },
]}
  • Rental item with options to book it starting from 12:00 for 1 hour, 2 hours, 3 hours and 4 hours.
  • Rental item with options to book it starting from 13:00 for 1 hour, 2 hours and 3 hours.
  • Rental item with options to book it starting from 14:00 for 1 hour and 2 hours.
  • Rental item with options to book it starting from 15:00 for 1 hour.
  • Rental item with options to book it starting from 17:00 for 1 hour.
  • Rental item with options to book it starting from 19:00 for 1 hour.

Rental items capturing request, booking price request and booking.

Rental related requests are simillar to trip items capturing request, except availabilityItemId parameter. For rentals it should contain a string which consists of availability item ids included in selected time slot separated with commas.

Capturing request example. 
{
    "availabilityItemId": "42964359120_rental_20161025120000_20161025120000,42964359120_rental_20161026120000_20161026120000,42964359120_rental_20161027120000_20161027120000",
    "priceCategories": [
        {
            "7802575": 1
        }
    ],
    "duration": "PT35M",
    "reference": ""
}

Authentication

Overview

API v2 supports OAuth2 authentication to get access to the data. You will be provided with client_id and client_secret which you'll use to authenticate yourself in the system.

Getting Access Token

The first thing you need to do is to get access token which you will then use will all your requests. This token is valid for 1 hour only. When it expires, you will need to request another one.

You can get you access token by POSTing to the /oauth2/token endpoint the following parameters:

  • grant_type (this should always be "client_credentials")
  • client_id
  • client_secret

Example Request:

$ curl --data "grant_type=client_credentials&client_id=username&client_secret=password" https://api2.trekksoft.com/oauth2/token

Example Response:

{
    "access_token": "79ab80aba81592906b43a3d10d7c49c68cf0951a",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": null
}

Authorization of requests

Once you have a valid access token, you will need to use it to sign all requests made to the TrekkSoft API.

This is done by providing Authorization HTTP header along with each of your requests in the following format:

Authorization: <token_type> <access_token>

Example Request:

$ curl -k -H"Authorization: Bearer 79ab80aba81592906b43a3d10d7c49c68cf0951a" https://api2.trekksoft.com/activities?limit=1

Activities

Activities List

GET/activities

Gets a list of activities information

Request Parameters

Name Required Type Description
id Optional Array Filter for activity IDs. Could be one (or several) IDs
language Optional String Filter for activity language. If not provided, activity details in merchant's default language will be returned
merchant Optional Array Filter for merchant code. Could be one (or several) merchants
category Optional Array Filter for activity category ID. Could be one (or several) categories
departureCountryCode Optional Array Filter for activity departure country. Could be one (or several) codes
departureCityId Optional Array Filter for activity departure city. Could be one (or several) codes
internal Optional Boolean Enable or disable internal guest fields. System hide the internal guest fields by default
isActive Optional Boolean Filter for activity status
onlyBookable Optional Boolean Filter for activities with active schedules
scheduleType Optional Array Works together with onlyBookable parameter. Filter by activity schedule type (can be trip, day_trip or voucher). Could be one (or several) codes
titleLike Optional String Filter for substring in activity title
limit Optional Integer Limit
offset Optional Integer Offset

Response

The response is an array of objects, each containing the following properties.
[    {
        "id": 61809,
        "merchant": "demo",
        "language": "nl",
        "defaultLanguage": "nl",
        "title": "Interlaken free walking tour",
        "description": "<p>Guided by local experts you experience and learn about the beauty and history of Interlaken and its surroundings.</p>",
        "highlights": "<p>Hide-aways<br />\r\nHistory of Interlaken<br />\r\nLegends of Interlaken</p>",
        "itinerary": "<p>Tour Dates</p>\r\n\r\n<p>Tours run daily<br />\r\nRain or Shine / whatever the weather :)</p>",
        "departure": {
            "country": {
                "code": "PL",
                "name": "Polen"
            },
            "city": {
                "id": 3102627,
                "locode": "BNA",
                "name": "Brodnica"
            }
        },
        "addons": [
            {
                "id": "30495",
                "type": "guest",
                "title": "Photo Package",
                "description": "<p>Have your picture taken by a professional</p>",
                "price": {
                    "amount": 15,
                    "currency": "USD"
                }
            },
            {
                "id": "31372",
                "type": "guest",
                "title": "Photo Package",
                "description": "<p>Have your picture taken by a professional</p>",
                "price": {
                    "amount": 15,
                    "currency": "USD"
                }
            }
        ],
        "customValues": [
            {
                "code": "activity_category",
                "title": "Activity Category",
                "key": "Walking",
                "value": "Walking"
            },
            {
                "code": "resource_costs",
                "title": "Resource costs per hour",
                "key": "0",
                "value": "0"
            }
        ],
        "activityFields": [
            {
                "code": "activity_category",
                "label": "Activity Category",
                "type": "select",
                "options": [
                    {
                        "key": "Walking",
                        "value": "Walking"
                    },
                    {
                        "key": "Hiking",
                        "value": "Hiking"
                    },
                    {
                        "key": "Flying",
                        "value": "Flying"
                    }
                ],
                "isRequired": true
            }
        ],
        "guestFields": [
            {
                "code": "gender",
                "label": "Gender",
                "type": "radio",
                "options": [
                    {
                        "key": "m",
                        "value": "Male"
                    },
                    {
                        "key": "f",
                        "value": "Female"
                    }
                ],
                "isRequired": false,
                "isHiddenWhileBooking": true
            },
            {
                "code": "firstname",
                "label": "First name",
                "type": "text",
                "options": null,
                "isRequired": true,
                "isHiddenWhileBooking": false
            },
            {
                "code": "lastname",
                "label": "Last name",
                "type": "text",
                "options": null,
                "isRequired": true,
                "isHiddenWhileBooking": false
            },
            {
                "code": "email",
                "label": "Email",
                "type": "text",
                "options": null,
                "isRequired": true,
                "isHiddenWhileBooking": false
            }
        ],
        "category": {
            "id": 14,
            "name": "Walking & Biking Tours"
        },
        "_links": {
            "videos": [],
            "documents": []
        },
        "fromPrice": {
            "amount": 3,
            "currency": "USD"
        },
        "isActive": "1",
        "route": [
            {
                "name": "Route: Włocławek",
                "latitude": "52.589808",
                "longitude": "18.908498"
            },
            {
                "name": "",
                "latitude": "34.125448",
                "longitude": "43.330078"
            }
        ],
        "navGroups": [
            3754
        ],
        "images": {
            "header": {
                "XS": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_headers/61809/150x100-1-30-273ee84451de99e8589f0205b8cd61be.jpg",
                "S": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_headers/61809/300x200-1-50-273ee84451de99e8589f0205b8cd61be.jpg",
                "M": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_headers/61809/600x400-1-50-273ee84451de99e8589f0205b8cd61be.jpg",
                "L": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_headers/61809/900x600-1-50-273ee84451de99e8589f0205b8cd61be.jpg",
                "XL": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_headers/61809/1200x800-1-50-273ee84451de99e8589f0205b8cd61be.jpg",
                "ORIGINAL": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_headers/61809/2000x2000-0-70-273ee84451de99e8589f0205b8cd61be.jpg"
            },
           "teaser": {
                "XS": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_teasers/61809/150x100-1-30-d669fb76e150c00967161ebd963092b1.jpg",
                "S": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_teasers/61809/300x200-1-50-d669fb76e150c00967161ebd963092b1.jpg",
                "M": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_teasers/61809/600x400-1-50-d669fb76e150c00967161ebd963092b1.jpg"
            },
            "gallery": null
        }
    },
...
]
NameTypeDescription
id Integer Activity ID
merchant String Merchant code
language String Language of the activity
defaultLanguage String Default(primary) language of the merchant
title String Activity's title in the current language
highlights String Activity's highlights in the current language (contains HTML markup)
itinerary String Activity's itinerary description in the current language (contains HTML markup)
customValues Array Extra details for the activity, different depending on merchant
customValues[0]['code'] String Custom field internal code
customValues[0]['title'] String Title of the custom field in the current language
customValues[0]['value'] String Value of the custom field for this activity
customValues[0]['key'] String Internal value (id) of the custom field for this activity
guestFields Array A list of extra details which guests are required to fill in when booking this activity (merchant-defined)
guestFields[0]['code'] String Internal code of the guest field
guestFields[0]['label'] String Label which should be shown for the field (in current language)
guestFields[0]['type'] String Control type of the field. Possible options are
  • text - single line text field
  • textarea - multiline text field
  • radio - group of radio buttons
  • select - select box
  • date - datepicker
guestFields[0]['options'] Array A list of options to select from for field types radio and select. NULL for other field types
guestFields[0]['options'][0]['key'] String Option key (this should be sent to server when customer selects the option during booking process)
guestFields[0]['options'][0]['value'] String Option value (this should be shown to the customer)
guestFields[0]['isRequired'] Boolean Defines whether this field is required or optional
activityFields Array A list of extra fields for activity
activityFields[0]['code'] String Internal code of the activity field
activityFields[0]['label'] String Label which should be shown for the field (in current language)
activityFields[0]['type'] String Control type of the field. Possible options are
  • text - single line text field
  • textarea - multiline text field
  • radio - group of radio buttons
  • select - select box
  • date - datepicker
activityFields[0]['options'] Array A list of options to select from for field types radio and select. NULL for other field types
activityFields[0]['options'][0]['key'] String Option key (this should be sent to server when customer selects the option during booking process)
activityFields[0]['options'][0]['value'] String Option value (this should be shown to the customer)
activityFields[0]['isRequired'] Boolean Defines whether this field is required or optional
addons Array A list of addons available for this activity
addons[0][id] Integer Addon ID
addons[0][title] String Addon's title in the current language
addons[0][description] String Addon's description in the current language (contains HTML markup)
addons[0][type] String Type of the addon. Possible options are
  • item - activity-bound addon
  • guest - guest-bound addon
addons[0][price][amount] Float Price of this addon
addons[0][price][currency] String Currency of this addon
description String Activity's description in the current language (contains HTML markup)
departure Array Departure point for this activity. See options below for details
departure['country'] Array Departure country (code and name)
departure['city'] Array Departure city (id, UN/LOCODE and name)
category Array Category of the activity (id and name)
_links Array Links to additional resources for the activity (such as videos, documents). See options below for details
_links[videos] Array URL(s) for the activity's video(s)
_links['documents'] Array URL(s) for the activity's informational document(s)
fromPrice Array Starting price for this activity which is set up by merchant (for reference, actual price might differ depending on selected price categories and discounts during booking process). Might be NULL if there's nothing to sell or no price specified
fromPrice[amount] Float Starting price amount
fromPrice[currency] String Starting price currency (always matches owning merchant's default currency)
navGroups Array List of Mobile Navigation Groups IDs for this activity
images Array Activity's images with different sizes
images[header][XS] String Activity header image with max size 150x100
images[header][S] String Activity header image with max size 300x200
images[header][M] String Activity header image with max size 600x400
images[header][L] String Activity header image with max size 900x600
images[header][XL] String Activity header image with max size 1200x800
images[header][ORIGINAL] String Activity header image with max size 2000x2000 (can be 1500x900 or 1480x920 for example - it depends on width and height of the original image)
images[teaser][XS] String Teaser image with size max 150x100
images[teaser][S] String Teaser image with size max 300x200
images[teaser][M] String Teaser image with size max 600x400
images[gallery][0][XS] String Gallery image with size max 150x100
images[gallery][0][S] String Gallery image with size max 300x200
images[gallery][0][M] String Gallery image with size max 600x400
images[gallery][0][L] String Gallery image with size max 900x600
images[gallery][0][XL] String Gallery image with size max 1200x800
images[gallery][0][ORIGINAL] String Gallery image with size max 2000x2000

Single Activity

GET/activities/{activityId}

Gets information for the specific activity

Request Parameters

Name Required Type Description
activityId Required Integer [url parameter] Desired activity id
language Optional String Filter for activity language. If not provided, activity details in merchant's default language will be returned
internal Optional Boolean Enable or disable internal guest fields. System hide the internal guest fields by default

Response

The response is an object containing the following properties.
    {
        "id": 61809,
        "merchant": "demo",
        "language": "nl",
        "defaultLanguage": "nl",
        "title": "Interlaken free walking tour",
        "description": "<p>Guided by local experts you experience and learn about the beauty and history of Interlaken and its surroundings.</p>",
        "highlights": "<p>Hide-aways<br />\r\nHistory of Interlaken<br />\r\nLegends of Interlaken</p>",
        "itinerary": "<p>Tour Dates</p>\r\n\r\n<p>Tours run daily<br />\r\nRain or Shine / whatever the weather :)</p>",
        "departure": {
            "country": {
                "code": "PL",
                "name": "Polen"
            },
            "city": {
                "id": 3102627,
                "locode": "BNA",
                "name": "Brodnica"
            }
        },
        "addons": [
            {
                "id": "30495",
                "type": "guest",
                "title": "Photo Package",
                "description": "<p>Have your picture taken by a professional</p>",
                "price": {
                    "amount": 15,
                    "currency": "USD"
                }
            },
            {
                "id": "31372",
                "type": "guest",
                "title": "Photo Package",
                "description": "<p>Have your picture taken by a professional</p>",
                "price": {
                    "amount": 15,
                    "currency": "USD"
                }
            }
        ],
        "customValues": [
            {
                "code": "activity_category",
                "title": "Activity Category",
                "key": "Walking",
                "value": "Walking"
            },
            {
                "code": "resource_costs",
                "title": "Resource costs per hour",
                "key": "0",
                "value": "0"
            }
        ],
        "activityFields": [
            {
                "code": "activity_category",
                "label": "Activity Category",
                "type": "select",
                "options": [
                    {
                        "key": "Walking",
                        "value": "Walking"
                    },
                    {
                        "key": "Hiking",
                        "value": "Hiking"
                    },
                    {
                        "key": "Flying",
                        "value": "Flying"
                    }
                ],
                "isRequired": true
            }
        ],
        "guestFields": [
            {
                "code": "gender",
                "label": "Gender",
                "type": "radio",
                "options": [
                    {
                        "key": "m",
                        "value": "Male"
                    },
                    {
                        "key": "f",
                        "value": "Female"
                    }
                ],
                "isRequired": false,
                "isHiddenWhileBooking": true
            },
            {
                "code": "firstname",
                "label": "First name",
                "type": "text",
                "options": null,
                "isRequired": true,
                "isHiddenWhileBooking": false
            },
            {
                "code": "lastname",
                "label": "Last name",
                "type": "text",
                "options": null,
                "isRequired": true,
                "isHiddenWhileBooking": false
            },
            {
                "code": "email",
                "label": "Email",
                "type": "text",
                "options": null,
                "isRequired": true,
                "isHiddenWhileBooking": false
            }
        ],
        "category": {
            "id": 14,
            "name": "Walking & Biking Tours"
        },
        "_links": {
            "videos": [],
            "documents": []
        },
        "fromPrice": {
            "amount": 3,
            "currency": "USD"
        },
        "isActive": "1",
        "route": [
            {
                "name": "Route: Włocławek",
                "latitude": "52.589808",
                "longitude": "18.908498"
            },
            {
                "name": "",
                "latitude": "34.125448",
                "longitude": "43.330078"
            }
        ],
        "navGroups": [
            3754
        ],
        "images": {
            "header": {
                "XS": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_headers/61809/150x100-1-30-273ee84451de99e8589f0205b8cd61be.jpg",
                "S": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_headers/61809/300x200-1-50-273ee84451de99e8589f0205b8cd61be.jpg",
                "M": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_headers/61809/600x400-1-50-273ee84451de99e8589f0205b8cd61be.jpg",
                "L": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_headers/61809/900x600-1-50-273ee84451de99e8589f0205b8cd61be.jpg",
                "XL": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_headers/61809/1200x800-1-50-273ee84451de99e8589f0205b8cd61be.jpg",
                "ORIGINAL": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_headers/61809/2000x2000-0-70-273ee84451de99e8589f0205b8cd61be.jpg"
            },
           "teaser": {
                "XS": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_teasers/61809/150x100-1-30-d669fb76e150c00967161ebd963092b1.jpg",
                "S": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_teasers/61809/300x200-1-50-d669fb76e150c00967161ebd963092b1.jpg",
                "M": "https://d3rr2gvhjw0wwy.cloudfront.net/uploads/activity_teasers/61809/600x400-1-50-d669fb76e150c00967161ebd963092b1.jpg"
            },
            "gallery": null
        }
    }
NameTypeDescription
id Integer Activity ID
merchant String Merchant code
language String Language of the activity
defaultLanguage String Default(primary) language of the merchant
title String Activity's title in the current language
highlights String Activity's highlights in the current language (contains HTML markup)
itinerary String Activity's itinerary description in the current language (contains HTML markup)
customValues Array Extra details for the activity, different depending on merchant
customValues[0]['code'] String Custom field internal code
customValues[0]['title'] String Title of the custom field in the current language
customValues[0]['value'] String Value of the custom field for this activity
customValues[0]['key'] String Internal value (id) of the custom field for this activity
guestFields Array A list of extra details which guests are required to fill in when booking this activity (merchant-defined)
guestFields[0]['code'] String Internal code of the guest field
guestFields[0]['label'] String Label which should be shown for the field (in current language)
guestFields[0]['type'] String Control type of the field. Possible options are
  • text - single line text field
  • textarea - multiline text field
  • radio - group of radio buttons
  • select - select box
  • date - datepicker
guestFields[0]['options'] Array A list of options to select from for field types radio and select. NULL for other field types
guestFields[0]['options'][0]['key'] String Option key (this should be sent to server when customer selects the option during booking process)
guestFields[0]['options'][0]['value'] String Option value (this should be shown to the customer)
guestFields[0]['isRequired'] Boolean Defines whether this field is required or optional
activityFields Array A list of extra fields for activity
activityFields[0]['code'] String Internal code of the activity field
activityFields[0]['label'] String Label which should be shown for the field (in current language)
activityFields[0]['type'] String Control type of the field. Possible options are
  • text - single line text field
  • textarea - multiline text field
  • radio - group of radio buttons
  • select - select box
  • date - datepicker
activityFields[0]['options'] Array A list of options to select from for field types radio and select. NULL for other field types
activityFields[0]['options'][0]['key'] String Option key (this should be sent to server when customer selects the option during booking process)
activityFields[0]['options'][0]['value'] String Option value (this should be shown to the customer)
activityFields[0]['isRequired'] Boolean Defines whether this field is required or optional
addons Array A list of addons available for this activity
addons[0][id] Integer Addon ID
addons[0][title] String Addon's title in the current language
addons[0][description] String Addon's description in the current language (contains HTML markup)
addons[0][type] String Type of the addon. Possible options are
  • item - activity-bound addon
  • guest - guest-bound addon
addons[0][price][amount] Float Price of this addon
addons[0][price][currency] String Currency of this addon
description String Activity's description in the current language (contains HTML markup)
departure Array Departure point for this activity. See options below for details
departure['country'] Array Departure country (code and name)
departure['city'] Array Departure city (id, UN/LOCODE and name)
category Array Category of the activity (id and name)
_links Array Links to additional resources for the activity (such as videos, documents). See options below for details
_links[videos] Array URL(s) for the activity's video(s)
_links['documents'] Array URL(s) for the activity's informational document(s)
fromPrice Array Starting price for this activity which is set up by merchant (for reference, actual price might differ depending on selected price categories and discounts during booking process). Might be NULL if there's nothing to sell or no price specified
fromPrice[amount] Float Starting price amount
fromPrice[currency] String Starting price currency (always matches owning merchant's default currency)
navGroups Array List of Mobile Navigation Groups IDs for this activity
images Array Activity's images with different sizes
images[header][XS] String Activity header image with max size 150x100
images[header][S] String Activity header image with max size 300x200
images[header][M] String Activity header image with max size 600x400
images[header][L] String Activity header image with max size 900x600
images[header][XL] String Activity header image with max size 1200x800
images[header][ORIGINAL] String Activity header image with max size 2000x2000 (can be 1500x900 or 1480x920 for example - it depends on width and height of the original image)
images[teaser][XS] String Teaser image with size max 150x100
images[teaser][S] String Teaser image with size max 300x200
images[teaser][M] String Teaser image with size max 600x400
images[gallery][0][XS] String Gallery image with size max 150x100
images[gallery][0][S] String Gallery image with size max 300x200
images[gallery][0][M] String Gallery image with size max 600x400
images[gallery][0][L] String Gallery image with size max 900x600
images[gallery][0][XL] String Gallery image with size max 1200x800
images[gallery][0][ORIGINAL] String Gallery image with size max 2000x2000

Activities Departure Cities

GET/activities/departure-cities

List all activities departure cities

Request Parameters

Name Required Type Description
onlyBookable Optional Boolean Filter for activities with active schedules
scheduleType Optional Array Works together with onlyBookable parameter. Filter by activity schedule type (can be trip, day_trip or voucher). Multiple filters are possible

Response

The response is an object containing the following properties.
[
    {
        "id": 3102627,
        "locode": "BNA",
        "name": "Brodnica"
    },
    ...
]

NameTypeDescription
id Integer City ID
locode String City locode
name String City name

Activity Update Time

GET/activities/{activityId}/updated

Returns information about when activity was updated

Request Parameters

Name Required Type Description
activityId Required Integer [url parameter] Desired activity id

Response

The response is an object containing the following properties.
{
    "datetime": "2018-05-28 08:51:10",
    "timezone": "UTC"
}
NameTypeDescription
datetime String Date and Time data in Y-m-d H:i:s format
timezone String Timezone data

Bookings

Create a Booking

POST/bookings

Creates a Booking

Request Parameters

Name Required Type Description
items Optional Array Items to be booked, details are explained below
items[0]['availabilityCaptureReference'] Optional String Availability capture reference which should have previously been received at Capture Availability call. When booking is created, this reference will no longer be valid.
items[0]['availabilityItemId'] Required String One or group of Availability Item ID's (separated with comma) which need to be booked
items[0]['guests'][0]['occupancy'] Required Integer How many seats to occupy for guest
items[0]['guests'][0]['firstname'] Optional String Guest firstname
items[0]['guests'][0]['lastname'] Optional String Guest lastname
items[0]['guests'][0]['priceCategoryId'] Required Integer Guest price category ID
items[0]['guests'][0]['discountCode'] Optional String Discount code (if any)
items[0]['guests'][0]['addons'] Optional Array Ids of addons applied for this guest
items[0]['guests'][0]['customFields'] Optional Array A list of guest's custom field values in format id: value
items[0]['addons'] Optional Array Addons applied for this availability item: id and quantity
items[0]['note'] Optional String User note for this item
shopItems Optional Array List of shop items to be booked: id and quantity
vouchers Optional Array List of applied vouchers
note Optional String Booking note
customFields Optional Array A list of bookee's custom field values in format id: value
contact Required Array User contact details
contact['type'] Required String Contact type, possible values: email and mobile
contact['name'] Required String Contact name
contact['value'] Required String Contact value, i.e. "email" or "mobile number"
contact['notify'] Optional Boolean Flag specifying whether notification should be sent on this contact channel or not. True by default. Currently only email notifications are supported
multidiscount Optional Float Custom multidiscount percentage (only for agent bookings). Overrides default multidiscount (if there was any)
payment Optional Array Offline payment details (only for agent bookings). Omit it for creating a reservation. Details explained below
payment['treasurer'] Optional String Treasurer ID
payment['reference'] Optional Integer Payment reference ID
payment['amount'] Required Float Amount which user paid to the agent
payment['currency'] Required String Payment's currency
creditCard Optional Array Credit card info. Pass this information if you are paying by credit card. You can specify either payment or credit card
creditCard['ccnumber'] Required String Credit card number
creditCard['expiryYear'] Required Integer Expiration year
creditCard['expiryMonth'] Required Integer Expiration month
creditCard['name'] Required String Card holder name
creditCard['cvc'] Required Integer Security code (CVC)
payworks Optional Array Payworks transaction info. Pass this information if you are paying by Payworks.
payworks['transactionId'] Required String Transaction Identifier
number Optional String Custom booking number
agentCode Optional String Agent's code. If you want to change agent of the booking.

Response

The response is an object containing the following properties.
Name Type Description
id Integer Created Basket ID

List of Bookings

GET/bookings

Shows recent bookings

Request Parameters

Name Required Type Description
merchant Optional Array Filter for selling merchant. Could be one (or several) merchants. Multiple filters are possible
user Optional Array | String Filter for users emails. Could be one (or several) emails. Multiple filters are possible
q Optional String Filters by id, guest name, guest email, user name, user email, activity name
bookingDate Optional String Filters by booking date
activityDate Optional String Filters by activity start date
limit Optional Integer Limit of returned bookings. By default limit is 500
offset Optional Integer Offset of returned bookings

Response

The response is an array of objects, each containing the following properties. 
[{
    "id": 14751475,
    "idAlias": null,
    "bookingNumber": "1231",
    "externalNumber": null,
    "merchant": "demo",
    "total": 53,
    "subTotal": 53,
    "fullCaption": "1 x Actividad Amigo - Toledo Express Tour From Madrid",
    "onlineBookingFee": 0,
    "totalFees": 0,
    "balance": 0,
    "totalPayments": 53,
    "totalRefunds": 0,
    "totalDiscounts": 0,
    "rebates": 0,
    "currency": "USD",
    "conversionRate": 1,
    "createdAt": "2018-03-27T14:12:31+02:00",
    "items": [
        {
            "id": 16329661,
            "caption": "3/27/2018 7:45 AM",
            "remarks": null,
            "fullCaption": "Actividad Amigo - Toledo Express Tour From Madrid (3/27/2018 7:45 AM)",
            "activity": {
                "id": 170182,
                "merchant": "telecoming",
                "language": "es",
                "defaultLanguage": "es",
                "title": "Actividad Amigo - Toledo Express Tour From Madrid",
                "departure": {
                    "country": {
                        "code": "ES",
                        "name": "España"
                    },
                    "city": {
                        "id": 3117735,
                        "locode": "MAD",
                        "name": "Madrid"
                    }
                }
            },
            "availabilityItem": {
                "type": "trip",
                "availabilityItemId": "42964661776_trip_20180327074500_20180327124500",
                "startDate": "2018-03-27",
                "startTime": "07:45:00",
                "timezone": "Europe/Paris"
            },
            "price": 53,
            "multidiscount": 0,
            "guests": [
                {
                    "id": 14924113,
                    "createdAt": "2018-03-27T14:12:31+02:00",
                    "basketItemId": 16329661,
                    "basketId": 14751475,
                    "isReservation": false,
                    "basketPaymentStatus": "even",
                    "availabilityItemId": "42964661776_trip_20180327074500_20180327124500",
                    "activityId": "170182",
                    "merchantId": 34579,
                    "sellingMerchantId": 15873,
                    "name": "Anonymous",
                    "firstName": "Anonymous",
                    "lastName": "",
                    "email": null,
                    "phone": "+41722222222",
                    "remarks": null,
                    "currency": "USD",
                    "price": 53,
                    "pricePerSeat": 53,
                    "occupancy": 1,
                    "discount": null,
                    "ticket": "/gen/guest.pdf/14924113/15fcbbaf7f2ae7b267e155b4a6314f9e",
                    "multiDiscount": 0,
                    "priceCategory": {
                        "id": 8788579,
                        "name": "Adulto"
                    },
                    "barCode": "GUE-14751475-14924113",
                    "barcodeAlias": null,
                    "customValues": [
                        {
                            "key": "gender",
                            "value": "",
                            "type": "radio",
                            "label": "Gender"
                        },
                        {
                            "key": "firstname",
                            "value": "Anonymous",
                            "type": "text",
                            "label": "First and last name"
                        },
                        {
                            "key": "lastname",
                            "value": "",
                            "type": "text",
                            "label": "Private Booking ID"
                        }, ...
                    ],
                    "cancellation": null,
                    "checkedIn": false,
                    "resources": [],
                    "addons": []
                }
            ],
            "addons": [],
            "isCancelled": false
        }
    ],
    "itemsPrice": 53,
    "shopItems": [],
    "shopItemsPrice": 0,
    "vouchers": [],
    "vouchersDiscount": 0,
    "multidiscount": 0,
    "taxes": [],
    "fees": [],
    "note": "Call 15 minutes in advance",
    "user": {
        "id": "23627810",
        "name": "Trekksoft Support",
        "email": "support@trekksoft.com",
        "customValues": [
            {
                "key": "gender",
                "value": "",
                "type": "radio",
                "label": "Gender"
            },
            {
                "key": "firstname",
                "value": "Trekksoft",
                "type": "text",
                "label": "First name"
            },
            {
                "key": "lastname",
                "value": "Support",
                "type": "text",
                "label": "Last name"
            }, ...
        ]
    },
    "channel": "Mobile Backend App",
    "agent": {
        "id": "60463",
        "name": "1234",
        "commission": "10.00",
        "email": "support@trekksoft.com"
    },
    "paymentStatus": "even",
    "status": "paid",
    "isReservation": false,
    "payments": [
        {
            "id": 2657773,
            "paymentReference": {
                "id": null,
                "name": null
            },
            "treasurerType": "agent",
            "treasurerReference": "agent-60463",
            "fundingInstrumentDisplayText": null,
            "amount": 53,
            "comment": "Payment",
            "channel": null,
            "createdAt": "2018-03-27T14:12:31+0200"
        }
    ],
    "treasurers": {
        "trekksoft": {
            "id": "trekksoft",
            "name": "TrekkSoft",
            "possibleRefundAmount": 0
        }, ...
    },
    "combinedTicket": "/gen/combined.pdf/14751475/e03a842f1bf7ab4af2aa7604083b5628",
    "marketplace": null
},
...
]
Name Type Description
id Integer Basket ID
merchant String Selling merchant
total Float Basket total
currency String Currency of the booking
conversionRate Float Conversion rate
createdAt String Date and time of basket creation
items Array Items list, details are explained below
items[0]['id'] Integer Item id
items[0]['caption'] String
items[0]['activity']['id'] Integer Activity id
items[0]['activity']['merchant'] String Activity's owner merchant
items[0]['activity']['language'] String Language of the activity
items[0]['activity']['defaultLanguage'] String Default language of the activity
items[0]['activity']['title'] String Title of the activity
items[0]['activity']['departure'] Array Departure point for this activity. See options below for details
items[0]['activity']['departure']['country'] Array Departure country (code and name)
items[0]['activity']['departure']['city'] Array Departure city (id, UN/LOCODE and name)
items[0]['availabilityItem']['availabilityItemId'] String Availability Item ID
items[0]['availabilityItem']['startDate'] String Start date
items[0]['availabilityItem']['startTime'] String Start time
items[0]['availabilityItem']['timezone'] String Timezone
items[0]['availabilityItem']['guests'] Array Guest's info
itemsPrice Float Price for all items
shopItems Array List of shop items
shopItems[0]['id'] Integer Shop item ID
shopItems[0]['quantity'] Integer Quantity of the shop item
shopItems[0]['price'] Float Price for one shop item
shopItems[0]['total'] Float Total price for the shop item
shopItemsPrice Float Total price for all shop items
vouchers Array A list of vouchers codes along with discount amount for each voucher.
vouchersDiscount Float Total discount for all vouchers
multidiscount Float Multi-discount amount
taxes Array A list of basket taxes
taxes[0]['title'] String Title of the tax
taxes[0]['included'] Boolean Indicates whether the tax is included into the price or not
taxes[0]['type'] String Tax type, can be either percent or fixed
taxes[0]['value'] Array Tax value, structure depends on tax type.
  • percent: will contain "percent" param, e.g. {'percent': 10} means "10%"
  • fixed: will contain "amount" and "currency" params, e.g. {'amount':20, 'currency':'CHF'} means "CHF 20"
fees Array A list of fees
fees[0]['code'] String Code of the fee
fees[0]['value'] Float Amount of the fee
note String Custom note for the booking
user Object User's info
user.customValues Array Extra details for the user, different depending on merchant
user.customValues[0] Object Extra details for the user, different depending on merchant
agent Object Agent's info
payments Array Payment info. Each object in array contain fields:
  • id: 2568220
  • paymentReference: {"id": "4", "name": "Credit Card"}
  • treasurerType: "agent"
  • treasurerReference: "agent-115573"
  • fundingInstrumentDisplayText: null
  • amount: 189
  • comment: Payment
  • channel: null
  • createdAt: "2018-03-13T13:56:20+0100"
  • transactionId: "tra_b01225588343395694ae6e821acf"

Single Booking

GET/bookings/{bookingId}

Gets information for the specific booking

Request Parameters

Name Required Type Description
bookingId Required Integer [url parameter] Desired booking id
merchant Optional Array Filter for selling merchant. Multiple filters are possible

Response

The response is an object containing the following properties.
{
    "id": 14751475,
    "idAlias": null,
    "bookingNumber": "1231",
    "externalNumber": null,
    "merchant": "demo",
    "total": 53,
    "subTotal": 53,
    "fullCaption": "1 x Actividad Amigo - Toledo Express Tour From Madrid",
    "onlineBookingFee": 0,
    "totalFees": 0,
    "balance": 0,
    "totalPayments": 53,
    "totalRefunds": 0,
    "totalDiscounts": 0,
    "rebates": 0,
    "currency": "USD",
    "conversionRate": 1,
    "createdAt": "2018-03-27T14:12:31+02:00",
    "items": [
        {
            "id": 16329661,
            "caption": "3/27/2018 7:45 AM",
            "remarks": null,
            "fullCaption": "Actividad Amigo - Toledo Express Tour From Madrid (3/27/2018 7:45 AM)",
            "activity": {
                "id": 170182,
                "merchant": "telecoming",
                "language": "es",
                "defaultLanguage": "es",
                "title": "Actividad Amigo - Toledo Express Tour From Madrid",
                "departure": {
                    "country": {
                        "code": "ES",
                        "name": "España"
                    },
                    "city": {
                        "id": 3117735,
                        "locode": "MAD",
                        "name": "Madrid"
                    }
                }
            },
            "availabilityItem": {
                "type": "trip",
                "availabilityItemId": "42964661776_trip_20180327074500_20180327124500",
                "startDate": "2018-03-27",
                "startTime": "07:45:00",
                "timezone": "Europe/Paris"
            },
            "price": 53,
            "multidiscount": 0,
            "guests": [
                {
                    "id": 14924113,
                    "createdAt": "2018-03-27T14:12:31+02:00",
                    "basketItemId": 16329661,
                    "basketId": 14751475,
                    "isReservation": false,
                    "basketPaymentStatus": "even",
                    "availabilityItemId": "42964661776_trip_20180327074500_20180327124500",
                    "activityId": "170182",
                    "merchantId": 34579,
                    "sellingMerchantId": 15873,
                    "name": "Anonymous",
                    "firstName": "Anonymous",
                    "lastName": "",
                    "email": null,
                    "phone": "+41722222222",
                    "remarks": null,
                    "currency": "USD",
                    "price": 53,
                    "pricePerSeat": 53,
                    "occupancy": 1,
                    "discount": null,
                    "ticket": "/gen/guest.pdf/14924113/15fcbbaf7f2ae7b267e155b4a6314f9e",
                    "multiDiscount": 0,
                    "priceCategory": {
                        "id": 8788579,
                        "name": "Adulto"
                    },
                    "barCode": "GUE-14751475-14924113",
                    "barcodeAlias": null,
                    "customValues": [
                        {
                            "key": "gender",
                            "value": "",
                            "type": "radio",
                            "label": "Gender"
                        },
                        {
                            "key": "firstname",
                            "value": "Anonymous",
                            "type": "text",
                            "label": "First and last name"
                        },
                        {
                            "key": "lastname",
                            "value": "",
                            "type": "text",
                            "label": "Private Booking ID"
                        }, ...
                    ],
                    "cancellation": null,
                    "checkedIn": false,
                    "resources": [],
                    "addons": []
                }
            ],
            "addons": [],
            "isCancelled": false
        }
    ],
    "itemsPrice": 53,
    "shopItems": [],
    "shopItemsPrice": 0,
    "vouchers": [],
    "vouchersDiscount": 0,
    "multidiscount": 0,
    "taxes": [],
    "fees": [],
    "note": "Call 15 minutes in advance",
    "user": {
        "id": "23627810",
        "name": "Trekksoft Support",
        "email": "support@trekksoft.com",
        "customValues": [
            {
                "key": "gender",
                "value": "",
                "type": "radio",
                "label": "Gender"
            },
            {
                "key": "firstname",
                "value": "Trekksoft",
                "type": "text",
                "label": "First name"
            },
            {
                "key": "lastname",
                "value": "Support",
                "type": "text",
                "label": "Last name"
            }, ...
        ]
    },
    "channel": "Mobile Backend App",
    "agent": {
        "id": "60463",
        "name": "1234",
        "commission": "10.00",
        "email": "support@trekksoft.com"
    },
    "paymentStatus": "even",
    "status": "paid",
    "isReservation": false,
    "payments": [
        {
            "id": 2657773,
            "paymentReference": {
                "id": null,
                "name": null
            },
            "treasurerType": "agent",
            "treasurerReference": "agent-60463",
            "fundingInstrumentDisplayText": null,
            "amount": 53,
            "comment": "Payment",
            "channel": null,
            "createdAt": "2018-03-27T14:12:31+0200"
        }
    ],
    "treasurers": {
        "trekksoft": {
            "id": "trekksoft",
            "name": "TrekkSoft",
            "possibleRefundAmount": 0
        }, ...
    },
    "combinedTicket": "/gen/combined.pdf/14751475/e03a842f1bf7ab4af2aa7604083b5628",
    "marketplace": null
}
Name Type Description
id Integer Basket ID
merchant String Selling merchant
total Float Basket total
currency String Currency of the booking
conversionRate Float Conversion rate
createdAt String Date and time of basket creation
items Array Items list, details are explained below
items[0]['id'] Integer Item id
items[0]['caption'] String
items[0]['activity']['id'] Integer Activity id
items[0]['activity']['merchant'] String Activity's owner merchant
items[0]['activity']['language'] String Language of the activity
items[0]['activity']['defaultLanguage'] String Default language of the activity
items[0]['activity']['title'] String Title of the activity
items[0]['activity']['departure'] Array Departure point for this activity. See options below for details
items[0]['activity']['departure']['country'] Array Departure country (code and name)
items[0]['activity']['departure']['city'] Array Departure city (id, UN/LOCODE and name)
items[0]['availabilityItem']['availabilityItemId'] String Availability Item ID
items[0]['availabilityItem']['startDate'] String Start date
items[0]['availabilityItem']['startTime'] String Start time
items[0]['availabilityItem']['timezone'] String Timezone
items[0]['availabilityItem']['guests'] Array Guest's info
itemsPrice Float Price for all items
shopItems Array List of shop items
shopItems[0]['id'] Integer Shop item ID
shopItems[0]['quantity'] Integer Quantity of the shop item
shopItems[0]['price'] Float Price for one shop item
shopItems[0]['total'] Float Total price for the shop item
shopItemsPrice Float Total price for all shop items
vouchers Array A list of vouchers codes along with discount amount for each voucher.
vouchersDiscount Float Total discount for all vouchers
multidiscount Float Multi-discount amount
taxes Array A list of basket taxes
taxes[0]['title'] String Title of the tax
taxes[0]['included'] Boolean Indicates whether the tax is included into the price or not
taxes[0]['type'] String Tax type, can be either percent or fixed
taxes[0]['value'] Array Tax value, structure depends on tax type.
  • percent: will contain "percent" param, e.g. {'percent': 10} means "10%"
  • fixed: will contain "amount" and "currency" params, e.g. {'amount':20, 'currency':'CHF'} means "CHF 20"
fees Array A list of fees
fees[0]['code'] String Code of the fee
fees[0]['value'] Float Amount of the fee
note String Custom note for the booking
user Object User's info
user.customValues Array Extra details for the user, different depending on merchant
user.customValues[0] Object Extra details for the user, different depending on merchant
agent Object Agent's info
payments Array Payment info. Each object in array contain fields:
  • id: 2568220
  • paymentReference: {"id": "4", "name": "Credit Card"}
  • treasurerType: "agent"
  • treasurerReference: "agent-115573"
  • fundingInstrumentDisplayText: null
  • amount: 189
  • comment: Payment
  • channel: null
  • createdAt: "2018-03-13T13:56:20+0100"
  • transactionId: "tra_b01225588343395694ae6e821acf"

Calculate Booking Price

GET/bookingPrices

Calculates Booking Price

Request Parameters

Name Required Type Description
items Optional Array Items for which price should be calculated. Details are explained below
items[0]['availabilityItemId'] Required String Availability Item ID
items[0]['guests'][0]['occupancy'] Required Integer How many seats to occupy for guest
items[0]['guests'][0]['priceCategoryId'] Required Integer Guest price category ID
currency Required String Currency which should be used for calculation
items[0]['guests'][0]['discountCode'] Optional String Discount code (if any)
items[0]['guests'][0]['addons'] Optional Array Addons applied for this guest: id and quantity. [{id:12, quantity:2}, ...]
items[0]['addons'] Optional Array Addons applied for this availability item: id and quantity. [{id:12, quantity:2}, ...]
shopItems Optional Array List of shop items: id and quantity. [{id:3, quantity:1}, ...]
vouchers Optional Array List of applied vouchers. ['ubercode1', 'vouc2015']
multidiscount Optional Float Custom multidiscount percentage (only for agent bookings). Overrides default multidiscount (if there was any)

Response

The response is an object containing the following properties.
{
    "currency": "CHF",
    "total": 965.48,
    "downPayment": 965.48,
    "items": [
        {
            "availabilityItemId": "42964356352_voucher_4f4c80ff65979854fb36535f8e915283",
            "guests": [
                {
                    "priceCategoryId": "7791680",
                    "price": 566.54,
                    "addonsPrice": 0,
                    "addons": [],
                    "downPayment": 566.54,
                    "total": 566.54,
                    "discountAmount": 0
                }
            ],
            "addons": [],
            "downPayment": 566.54,
            "total": 566.54
        }
    ],
    "itemsDownPayment": 566.54,
    "itemsPrice": 566.54,
    "discountPrice": 0,
    "shopItems": [],
    "shopItemsPrice": 0,
    "vouchers": [],
    "vouchersDiscount": 0,
    "multidiscount": {
        "percent": 0,
        "amount": 0
    },
    "taxes": [
        {
            "title": "Iva (22%)",
            "included": false,
            "type": "tax",
            "value": 124.64
        }, ...
    ],
    "fees": []
}
Name Type Description
merchant String Selling merchant
total Float Basket total
currency String Currency of the booking
conversionRate Float Conversion rate
createdAt String Date and time of basket creation
items Array Items list, details are explained below
items[0]['availabilityItemId'] String Availability Item ID
items[0]['guests'] Array List of guest's prices: price, addonPrice, discountAmount, total
items[0]['total'] Float Total item price
itemsPrice Float Price for all items
discountPrice Float Discount code total amount (if discount exists)
shopItems Array List of shop items
shopItems[0]['id'] Integer Shop item ID
shopItems[0]['quantity'] Integer Quantity of the shop item
shopItems[0]['price'] Float Price for one shop item
shopItems[0]['total'] Float Total price for the shop item
shopItemsPrice Float Total price for all shop items
vouchers Array A list of vouchers codes along with discount amount for each voucher.
vouchersDiscount Float Total discount for all vouchers
multidiscount Array Multidiscount percent and amount
taxes Array A list of basket taxes
taxes[0]['title'] String Title of the tax
taxes[0]['included'] Boolean Indicates whether the tax is included into the price or not
taxes[0]['type'] String Tax type, can be either percent or fixed
taxes[0]['value'] Array Tax value, structure depends on tax type.
  • percent: will contain "percent" param, e.g. {'percent': 10} means "10%"
  • fixed: will contain "amount" and "currency" params, e.g. {'amount':20, 'currency':'CHF'} means "CHF 20"
fees Array A list of fees
fees[0]['code'] String Code of the fee
fees[0]['value'] Float Amount of the fee

Validate Discount Code

GET/discountCodes

Validates Discount Code

Request Parameters

Name Required Type Description
discountCode Required String Discount code
activityId Required Integer Activity for which discount code is to be applied
price Required Integer Amount on which discount is to be applied
currency Required String Currency or currency locale
priceCategoryId Optional Integer Id of price category

Response

The response is an object containing the following properties.
Name Type Description
price Float Price on which discount will be applied
formattedPrice String Price on which discount will be applied, user-friendly
isValid Boolean Is discount code valid?
discount Float Discount percentage
discountAmount Float Discount amount
formattedDiscountAmount String Discount amount, user-friendly
newPrice Float Price which will be after applying discount
formattedNewPrice String Price which will be after applying discount, user-friendly

Validate Vouchers

GET/vouchers

Validate Vouchers

Request Parameters

Name Required Type Description
code Required Array Array of voucher codes
basketItemId Optional Array Array of basketItemId
shopItemId Optional Array Array of shopItemId

Response

The response is an array of objects, each containing the following properties.
Name Type Description
isValid Boolean Is valid voucher or not?
code String Voucher code
amount Float Voucher amount
currency String Voucher currency
error String If voucher is invalid, this field will return error description

Cancel Booking

PUT/bookings/{bookingId}

Cancels specific booking

Request Parameters

Name Required Type Description Example
bookingId Required Integer ID of booking to cancel 10037406
reason Required String The reason for the cancellation No longer traveling
refundType Optional String Treasurer to refund with mandator-10
refundFee Optional Boolean Adds fee to refund true
note Optional String Whatever note you want to add to the booking Refunded Customer

Response

The response is an object containing the following properties.
Name Type Description Example
id Integer ID of canceled booking 10037406

Set custom booking number

POST/booking-number

Set a custom number to a booking

Request Parameters

Name Required Type Description Example
id Required Integer ID of booking 10037406
number Required String Any custom identifier order#2231

Response

The response is an object containing the following properties.
Name Type Description Example
id Integer ID of affected booking 10037406

Send tickets

POST/booking/{bookingId}/tickets

Send all tickets of booking to the given email

Request Parameters

Name Required Type Description Example
bookingId Required Integer ID of booking 10037406
recipient Required String Email address to send tickets to mail@example.com
subject Optional String Subject of the email Tickets of booking #10037406
body Optional String Body of the email Here are tickets you've requested

Set basket item remarks

PUT/booking/item/{bookingItemId}/remarks

Sets basket item remarks

Request Parameters

Name Required Type Description Example
bookingItemId Required Integer Booking item ID 342124
remarks Required String Remarks to set Some remarks

Cancel Booking Item

PUT/booking/item/{bookingItemId}/cancel

Cancels a booking item

Request Parameters

Name Required Type Description Example
bookingItemId Required Integer Booking item ID 342124
refundType Required String Treasurer to refund with mandator-10
reason Optional String Comment for the reason of cancellation Trip was cancelled
refundFee Optional Boolean Refund online booking fee after canceling this item false

Response

The response is an object containing the following properties.
Name Type Description
id Integer ID of the canceled booking item

Cancel Basket Item Addon

PUT/booking/item/addon/{id}/cancel

Cancels a basket item addon

Request Parameters

Name Required Type Description Example
id Required Integer Addon ID 23
refundType Required String Treasurer to refund with mandator-10
refundFee Optional Boolean Adds fee to refund true
reason Optional String Comment for the reason of cancellation Trip was cancelled

Response

The response is an object containing the following properties.
Name Type Description Example
id Integer ID of the canceled addon 23

Rebook Booking Item

PUT/booking/item/{bookingItemId}/rebook

Rebooks a booking item

Request Parameters

Name Required Type Description Example
bookingItemId Required Integer Booking item ID 342124
itemId Required String Id of the item to be booked 4296430_trip_20150928093000_20150928143000
ruleId Required Integer Rule id of the item, together with itemId it uniquely identifies an item 42964302142
priceCategoryId Optional Integer Price category id to be rebooked into. If price category id is not specified current price category of the guest will be used 1554
price Optional Float If price is not specified price of the price category will be used 10.50
seats Optional Integer Number of seats. If seats are not specified number of seats from the guest will be used 1

Add payment

POST/booking/{bookingId}/payment

Adds payment to a booking

Request Parameters

Name Required Type Description Example
bookingId Required Integer ID of booking 10037406
amount Required Float Amount of the payment 10.99
treasurerType Required String Who is receiving or received the payment mandator-15873
comment Optional String Comment to the payment Cash over the counter
referenceId Optional Integer Payment reference ID 22

Response

The response is an object containing the following properties.
Name Type Description Example
paymentId Integer ID of created payment 822507

Add refund

POST/booking/{bookingId}/refund

Adds refund to a booking

Request Parameters

Name Required Type Description Example
bookingId Required Integer ID of booking 10037406
amount Required Float Amount of the refund 10.99
refundType Required String Treasurer to refund with agent-15873
reason Optional String Reason of the refund Trip was cancelled
transactionId Required when refundType is 'trekksoft' String ID of transaction which is going to be refunded tra_b012df5882234395432ae6e821acf

Response

The response is an object containing the following properties.
Name Type Description Example
paymentId Integer ID of created refund 822507

Guests

Single Guest

GET/guest/{id}

Requests single guest by ID

Request Parameters

Name Required Type Description
id Required Integer [url parameter] Desired guest ID

Response

The response is an object containing the following properties.
{
    "id": 14924113,
    "createdAt": "2018-03-27T14:12:31+02:00",
    "basketItemId": 16329661,
    "basketId": 14751475,
    "activityId": 170182,
    "isReservation": false,
    "basketPaymentStatus": "even",
    "firstName": "Anonymous",
    "lastName": "",
    "name": "Anonymous",
    "email": null,
    "remarks": null,
    "currency": "USD",
    "price": 53,
    "pricePerSeat": 53,
    "occupancy": 1,
    "discount": null,
    "ticket": "/gen/guest.pdf/14924113/15fcbbaf7f2ae7b267e155b4a6314f9e",
    "multiDiscount": 0,
    "priceCategory": {
        "id": 8788579,
        "name": "Adulto"
    },
    "barCode": "GUE-14751475-14924113",
    "customValues": [
        {
            "key": "gender",
            "value": "",
            "type": "radio",
            "label": "Gender"
        }, ...
    ],
    "cancellation": null,
    "checkedIn": false,
    "resources": [],
    "addons": []
}
Name Type Description
id Integer Guest ID
createdAt String
basketId Integer Booking ID
basketItemId Integer Booking Item ID
isReservation Boolean Indicates whether this guest is a reserved or booked
basketPaymentStatus String Booking payment status
firstName String Guest first name
lastName String Guest last name
name String Guest full name
email String Guest email
remarks String Remarks about guest
currency String Currency of the guest
price Float Price of the guest
pricePerSeat Float Price per seat
occupancy Integer How many seats to occupy for guest
discount Float Discount percentage
ticket String Path to the ticket
multiDiscount Float Guest discount amount (in numeric format) which was applied
priceCategory[id] Integer Guest price category ID
priceCategory[name] String Guest price category name
barCode String Guest bar code string
customValues Array Extra details of the guest
customValues[0]['code'] String Custom field internal code
customValues[0]['title'] String Title of the custom field in the current language
customValues[0]['value'] String Value of the custom field of the guest
customValues[0]['key'] String Internal value (id) of the custom field
cancellation Object Data about guest cancellation
cancellation.reason String The reason for the cancellation
cancellation.datetime String The datetime of cancellation
checkedIn Boolean Checked in the guest or not
resources Array List of resources which are applied for this guest
addons Array Array of addons applied for this guest

Guest list

GET/guests

Requests list of Guests. The response will be an array of guests (see Single Guest response)

Request Parameters

Name Required Type Description
id Optional Array Filter for guest IDs. Could be one (or several) IDs. Multiple filters are possible
availabilityItemId Optional Array Filter guest by availability item id. Could be one (or several) IDs. Multiple filters are possible
bookingId Optional Integer Filter guest by booking id
phone Optional String Filter guest by phone
name Optional String Filter guest by name

Response

The response will be an array of guests (see Single Guest response) 
[{
    "id": 14924113,
    "createdAt": "2018-03-27T14:12:31+02:00",
    "basketItemId": 16329661,
    "basketId": 14751475,
    "activityId": 170182,
    "isReservation": false,
    "basketPaymentStatus": "even",
    "firstName": "Anonymous",
    "lastName": "",
    "name": "Anonymous",
    "email": null,
    "remarks": null,
    "currency": "USD",
    "price": 53,
    "pricePerSeat": 53,
    "occupancy": 1,
    "discount": null,
    "ticket": "/gen/guest.pdf/14924113/15fcbbaf7f2ae7b267e155b4a6314f9e",
    "multiDiscount": 0,
    "priceCategory": {
        "id": 8788579,
        "name": "Adulto"
    },
    "barCode": "GUE-14751475-14924113",
    "customValues": [
        {
            "key": "gender",
            "value": "",
            "type": "radio",
            "label": "Gender"
        }, ...
    ],
    "cancellation": null,
    "checkedIn": false,
    "resources": [],
    "addons": []
},
...
]

Check In

POST/guest/{id}/check-in

Checks In guest

Request Parameters

Name Required Type Description
id Required Integer [url parameter] Guest ID

Response

The response is an object containing the following properties.
Name Type Description
checkedIn Boolean Status of checked in guest

Check Out

POST/guest/{id}/check-out

Checks Out guest

Request Parameters

Name Required Type Description
id Required Integer [url parameter] Guest ID

Response

The response is an object containing the following properties.
Name Type Description
checkedOut Boolean Status of checked out guest

Cancel Guest

PUT/guest/{id}/cancel

Cancels a guest

Request Parameters

Name Required Type Description
id Required Integer [url parameter] Guest ID
refundType Required String Treasurer to refund with
refundFee Optional Boolean Adds fee to refund
reason Optional String Comment for the reason of cancellation

Response

The response is an object containing the following properties.
Name Type Description
id Integer ID of the canceled guest

Cancel Guest Addon

PUT/guest/addon/{id}/cancel

Cancels a guest addon

Request Parameters

Name Required Type Description
id Required Integer [url parameter] Guest Addon ID
refundType Required String Treasurer to refund with
refundFee Optional Boolean Adds fee to refund
reason Optional String Comment for the reason of cancellation

Response

The response is an object containing the following properties.
Name Type Description
id Integer ID of the canceled addon

Rebook Guest

PUT/guest/{id}/rebook

Rebooks a guest

Request Parameters

Name Required Type Description
id Required Integer Guest ID
itemId Required String Id of the item to be booked
ruleId Required Integer Rule id of the item, together with itemId it uniquely identifies an item
priceCategoryId Optional Integer Price category id to be rebooked into. If price category id is not specified current price category of the guest will be used
price Optional Float If price is not specified price of the price category will be used
seats Optional Integer Number of seats. If seats are not specified number of seats from the guest will be used

Availabilities

Request Availabilities

GET/availabilities

Requests which activities are available

Request Parameters

Name Required Type Description
activityId Optional Array Filter for activity IDs. Could be one (or several) IDs. Multiple filters are possible
titleLike Optional String Filter by activity title. Could be a part of the full title.
type Optional Array Availability types to filter for. Should be one (or several) of trip, day_trip, voucher
bookingTime Optional String Date/time in ISO 8601 format of when you expect booking to happen (usually you should set it to the current date and time). It would filter out availability items which are not bookable after this time.
seats Optional Integer Quantity of required seats (defaults to 1). Providing this number would filter out availability items which don't have enough remaining seats for the booking. Bear in mind that this only applies generic filter for availability items, individual limits per price categories might apply. If your oauth key allows overbooking for certain merchants, this filter would be ignored.
activeOnly Optional Boolean Set this to false to get items for all availability items (including disabled/blocked ones).
withExclusive Optional Boolean Set this to true to include exclusive private events in the result
withCustom Optional Boolean Set this to false to exclude custom trips (default true)
onlyBooked Optional Boolean Return availabilities that were booked at least once
onlyNotBooked Optional Boolean Return availabilities that never booked
category Optional Array Price categories to search for in format (id=>available seats)
merchant Optional Array Filter for merchant code. Could be one (or several) merchants. Multiple filters are possible
startsFrom Optional String Activity start datetime range begin
startsTo Optional String Activity start date range end
departureTime Optional String Departure time
language Optional String Filter for availability language. If not provided, availability details in merchant's default language will be returned
limit Optional Integer Limit
offset Optional Integer Offset

Response

The response is an array of objects, each containing the following properties.
[{
    "type": "voucher",
    "availabilityItemId": "42964356352_voucher_4f4c80ff65979854fb36535f8e915283",
    "availabilityRuleId": 42964356352,
    "latestBookingTime": null,
    "merchant_id": "15873",
    "merchant": "demo",
    "language": "nl",
    "defaultLanguage": "nl",
    "activityId": 61809,
    "activityTitle": "Interlaken free walking tour",
    "startDate": null,
    "startTime": null,
    "endDate": null,
    "endTime": null,
    "timezone": "Europe/Berlin",
    "duration": null,
    "bookingNote": "",
    "categories": [
        {
            "id": 7791680,
            "name": "Miami",
            "description": "/ noches",
            "availableSeats": null,
            "capacity": null,
            "occupancy": 14,
            "occupancyPaid": 14,
            "minSeats": 1,
            "maxSeats": 1,
            "isCustom": false,
            "price": {
                "amount": 570,
                "currency": "USD"
            },
            "downPayment": {
                "type": "full"
            }
        }
    ],
    "availableSeats": 51,
    "capacity": 70,
    "occupancy": 19,
    "occupancyPaid": 14,
    "occupancyStatus": "bookedsome",
    "isExclusive": false,
    "isActive": true,
    "isParent": false,
    "sortingToken": "0_miami---42964356352",
    "remarks": "",
    "startsAt": null
},
...
]
Name Type Description
type String Availability type. Can be trip, day_trip, voucher
merchant String Merchant code
merchant_id String Merchant ID
language String Language
defaultLanguage String Merchant's default language
activityId Integer Activity ID
activityTitle String Activity Title
availabilityRuleId String Availability Rule ID
availabilityItemId String Availability Item ID
latestBookingTime String Latest time when a booking is allowed. After this time a booking will not be possible if you don't have permissions to book past trips
startDate String Departure Date
startTime String Departure Time
endDate string|null Until Date
endTime string|null Until Time
timezone string Timezone
duration String Duration in ISO 8601 format
bookingNote String Booking Note
availableSeats Integer Quantity of available seats for availability. Note that individual limits for each category might be applied (see categories section below)
capacity Integer Capacity of availability (e.g. how many people can the boat contain). Note that individual limits for each category might be applied (see categories section below)
occupancy Integer Occupancy of availability (how many seats are reserved)
occupancyPaid Integer Number of paid seats
occupancyStatus String Available seats status. Can be inactive, resource-full, full, almostfull (more than 80% booked), bookedsome (booked at least 1), free
categories Array A list of all booking options, see details below
categories[id] Integer Price category ID
categories[name] String Price category name
categories[description] String Price category description
categories[availableSeats] Integer Quantity of available seats for price category (price categories with no available seats are not returned). Might return NULL if there is no limit for price category (in this case global available seats limit is applied, see availableSeats option above)
categories[capacity] Integer Capacity of availability for price category. Might return NULL if there is no limit for price category (in this case global capacity limit is applied, see capacity option above)
categories[occupancy] Integer Occupancy of availability for price category
categories[minSeats] Integer Minimum number of seats which is allowed for this price category (used for group bookings)
categories[maxSeats] Integer Maximum number of seats which is allowed for this price category
categories[isCustom] Boolean Whether this category is custom or not
categories[price][amount] Float Price of this price category
categories[price][currency] String Currency of this price category
isCustom Boolean Whether this availability is custom trip
isExclusive Boolean Whether this availability is exclusive or not
isActive Boolean Whether this availability is active or not
isParent Boolean Whether this availability is parent for other or not
remarks String Special availability remarks
sortingToken String Availability sorting token

Request Activity Availabilities

GET/activities/{activityId}/availabilities

Request Availabilities for the given activityId

Request Parameters

Name Required Type Description
activityId Required Integer [url parameter] Desired activity ID
type Optional Array Availability types to filter for. Should be one (or several) of trip, day_trip, voucher
bookingTime Optional String Date/time in ISO 8601 format of when you expect booking to happen (usually you should set it to the current date and time). It would filter out availability items which are not bookable after this time.
seats Optional Integer Quantity of required seats (defaults to 1). Providing this number would filter out availability items which don't have enough remaining seats for the booking. Bear in mind that this only applies generic filter for availability items, individual limits per price categories might apply. If your oauth key allows overbooking for certain merchants, this filter would be ignored.
activeOnly Optional Boolean Set this to false to get items for all availability items (including disabled/blocked ones).
withExclusive Optional Boolean Set this to true to include exclusive private events in the result
withCustom Optional Boolean Set this to false to exclude custom trips (default true)
onlyBooked Optional Boolean Return availabilities that were booked at least once
onlyNotBooked Optional Boolean Return availabilities that never booked
category Optional Array Price categories to search for in format (id=>available seats)
merchant Optional Array Filter for merchant code. Could be one (or several) merchants. Multiple filters are possible
startsFrom Optional String Activity start datetime range begin
startsTo Optional String Activity start date range end
departureTime Optional String Departure time
language Optional String Filter for availability language. If not provided, availability details in merchant's default language will be returned
limit Optional Integer Limit
offset Optional Integer Offset

Response

The response is an array of objects, each containing the following properties.
[{
    "type": "voucher",
    "availabilityItemId": "42964356352_voucher_4f4c80ff65979854fb36535f8e915283",
    "availabilityRuleId": 42964356352,
    "latestBookingTime": null,
    "merchant_id": "15873",
    "merchant": "demo",
    "language": "nl",
    "defaultLanguage": "nl",
    "activityId": 61809,
    "activityTitle": "Interlaken free walking tour",
    "startDate": null,
    "startTime": null,
    "endDate": null,
    "endTime": null,
    "timezone": "Europe/Berlin",
    "duration": null,
    "bookingNote": "",
    "categories": [
        {
            "id": 7791680,
            "name": "Miami",
            "description": "/ noches",
            "availableSeats": null,
            "capacity": null,
            "occupancy": 14,
            "occupancyPaid": 14,
            "minSeats": 1,
            "maxSeats": 1,
            "isCustom": false,
            "price": {
                "amount": 570,
                "currency": "USD"
            },
            "downPayment": {
                "type": "full"
            }
        }
    ],
    "availableSeats": 51,
    "capacity": 70,
    "occupancy": 19,
    "occupancyPaid": 14,
    "occupancyStatus": "bookedsome",
    "isExclusive": false,
    "isActive": true,
    "isParent": false,
    "sortingToken": "0_miami---42964356352",
    "remarks": "",
    "startsAt": null
},
...
]
Name Type Description
type String Availability type. Can be trip, day_trip, voucher
merchant String Merchant code
merchant_id String Merchant ID
language String Language
defaultLanguage String Merchant's default language
activityId Integer Activity ID
activityTitle String Activity Title
availabilityRuleId String Availability Rule ID
availabilityItemId String Availability Item ID
latestBookingTime String Latest time when a booking is allowed. After this time a booking will not be possible if you don't have permissions to book past trips
startDate String Departure Date
startTime String Departure Time
endDate string|null Until Date
endTime string|null Until Time
timezone string Timezone
duration String Duration in ISO 8601 format
bookingNote String Booking Note
availableSeats Integer Quantity of available seats for availability. Note that individual limits for each category might be applied (see categories section below)
capacity Integer Capacity of availability (e.g. how many people can the boat contain). Note that individual limits for each category might be applied (see categories section below)
occupancy Integer Occupancy of availability (how many seats are reserved)
occupancyPaid Integer Number of paid seats
occupancyStatus String Available seats status. Can be inactive, resource-full, full, almostfull (more than 80% booked), bookedsome (booked at least 1), free
categories Array A list of all booking options, see details below
categories[id] Integer Price category ID
categories[name] String Price category name
categories[description] String Price category description
categories[availableSeats] Integer Quantity of available seats for price category (price categories with no available seats are not returned). Might return NULL if there is no limit for price category (in this case global available seats limit is applied, see availableSeats option above)
categories[capacity] Integer Capacity of availability for price category. Might return NULL if there is no limit for price category (in this case global capacity limit is applied, see capacity option above)
categories[occupancy] Integer Occupancy of availability for price category
categories[minSeats] Integer Minimum number of seats which is allowed for this price category (used for group bookings)
categories[maxSeats] Integer Maximum number of seats which is allowed for this price category
categories[isCustom] Boolean Whether this category is custom or not
categories[price][amount] Float Price of this price category
categories[price][currency] String Currency of this price category
isCustom Boolean Whether this availability is custom trip
isExclusive Boolean Whether this availability is exclusive or not
isActive Boolean Whether this availability is active or not
isParent Boolean Whether this availability is parent for other or not
remarks String Special availability remarks
sortingToken String Availability sorting token

Request Single Availability

GET/availabilities/{availabilityItemId}

Request one Availability by its ID

Request Parameters

Name Required Type Description
availabilityItemId Required String [url parameter] Desired availability item ID
type Optional Array Availability types to filter for. Should be one (or several) of trip, day_trip, voucher
bookingTime Optional String Date/time in ISO 8601 format of when you expect booking to happen (usually you should set it to the current date and time). It would filter out availability items which are not bookable after this time.
seats Optional Integer Quantity of required seats (defaults to 1). Providing this number would filter out availability items which don't have enough remaining seats for the booking. Bear in mind that this only applies generic filter for availability items, individual limits per price categories might apply. If your oauth key allows overbooking for certain merchants, this filter would be ignored.
activeOnly Optional Boolean Set this to false to get items for all availability items (including disabled/blocked ones).
withExclusive Optional Boolean Set this to true to include exclusive private events in the result
withCustom Optional Boolean Set this to false to exclude custom trips (default true)
onlyBooked Optional Boolean Return availabilities that were booked at least once
onlyNotBooked Optional Boolean Return availabilities that never booked
category Optional Array Price categories to search for in format (id=>available seats)
merchant Optional Array Filter for merchant code. Could be one (or several) merchants. Multiple filters are possible
startsFrom Optional String Activity start datetime range begin
startsTo Optional String Activity start date range end
departureTime Optional String Departure time
language Optional String Filter for availability language. If not provided, availability details in merchant's default language will be returned
limit Optional Integer Limit
offset Optional Integer Offset

Response

The response is an object containing the following properties.
{
    "type": "voucher",
    "availabilityItemId": "42964356352_voucher_4f4c80ff65979854fb36535f8e915283",
    "availabilityRuleId": 42964356352,
    "latestBookingTime": null,
    "merchant_id": "15873",
    "merchant": "demo",
    "language": "nl",
    "defaultLanguage": "nl",
    "activityId": 61809,
    "activityTitle": "Interlaken free walking tour",
    "startDate": null,
    "startTime": null,
    "endDate": null,
    "endTime": null,
    "timezone": "Europe/Berlin",
    "duration": null,
    "bookingNote": "",
    "categories": [
        {
            "id": 7791680,
            "name": "Miami",
            "description": "/ noches",
            "availableSeats": null,
            "capacity": null,
            "occupancy": 14,
            "occupancyPaid": 14,
            "minSeats": 1,
            "maxSeats": 1,
            "isCustom": false,
            "price": {
                "amount": 570,
                "currency": "USD"
            },
            "downPayment": {
                "type": "full"
            }
        }
    ],
    "availableSeats": 51,
    "capacity": 70,
    "occupancy": 19,
    "occupancyPaid": 14,
    "occupancyStatus": "bookedsome",
    "isExclusive": false,
    "isActive": true,
    "isParent": false,
    "sortingToken": "0_miami---42964356352",
    "remarks": "",
    "startsAt": null
}
Name Type Description
type String Availability type. Can be trip, day_trip, voucher
merchant String Merchant code
merchant_id String Merchant ID
language String Language
defaultLanguage String Merchant's default language
activityId Integer Activity ID
activityTitle String Activity Title
availabilityRuleId String Availability Rule ID
availabilityItemId String Availability Item ID
latestBookingTime String Latest time when a booking is allowed. After this time a booking will not be possible if you don't have permissions to book past trips
startDate String Departure Date
startTime String Departure Time
endDate string|null Until Date
endTime string|null Until Time
timezone string Timezone
duration String Duration in ISO 8601 format
bookingNote String Booking Note
availableSeats Integer Quantity of available seats for availability. Note that individual limits for each category might be applied (see categories section below)
capacity Integer Capacity of availability (e.g. how many people can the boat contain). Note that individual limits for each category might be applied (see categories section below)
occupancy Integer Occupancy of availability (how many seats are reserved)
occupancyPaid Integer Number of paid seats
occupancyStatus String Available seats status. Can be inactive, resource-full, full, almostfull (more than 80% booked), bookedsome (booked at least 1), free
categories Array A list of all booking options, see details below
categories[id] Integer Price category ID
categories[name] String Price category name
categories[description] String Price category description
categories[availableSeats] Integer Quantity of available seats for price category (price categories with no available seats are not returned). Might return NULL if there is no limit for price category (in this case global available seats limit is applied, see availableSeats option above)
categories[capacity] Integer Capacity of availability for price category. Might return NULL if there is no limit for price category (in this case global capacity limit is applied, see capacity option above)
categories[occupancy] Integer Occupancy of availability for price category
categories[minSeats] Integer Minimum number of seats which is allowed for this price category (used for group bookings)
categories[maxSeats] Integer Maximum number of seats which is allowed for this price category
categories[isCustom] Boolean Whether this category is custom or not
categories[price][amount] Float Price of this price category
categories[price][currency] String Currency of this price category
isCustom Boolean Whether this availability is custom trip
isExclusive Boolean Whether this availability is exclusive or not
isActive Boolean Whether this availability is active or not
isParent Boolean Whether this availability is parent for other or not
remarks String Special availability remarks
sortingToken String Availability sorting token

Capture Availability

POST/reservations

Captures (reserves) specific availability for future booking. Usually done on the checkout page just before placing a booking.
Important note: make sure you take into consideration minSeats and maxSeats information for availability.
E.g. if you want to book 3 single seat items (maxSeats = 1) for price category 567, you have to treat them as separate: [{567:1}, {567:1}, {567:1}]
For group seats (minSeats > 1) you need to specify quantity directly: [{765: 3}]
If minSeats, maxSeats or available seats limitations are exceeded, response with status 400 will be returned (with error details) and items will not be captured.

Request Parameters

Name Required Type Description Example
availabilityItemId Required String Availability item ID 42964301287_trip_20150310000000
priceCategories Required Array Price categories to be captured in [{"id":"quantity"},...] format. Alternatively {"id":"quantity", ...} format can be used. [{12220:1}, {12223: 2}]
duration Optional String Specifies for how long availability should be captured. Set this to the minimal required duration you require so that not to block bookings for other users. Note that server might limit capture duration time in case you request too long duration. Duration is set in ISO 8601 format PT300S
reference Optional String Use it for re-capturing. If reference is provided, it will be uncaptured first and a new capture is created with details provided in this request EB573591CEF285C12701

Uncapture Availability

DELETE/reservations/{reference}

Uncaptures (releases) previously captured availability. This is usually needed when basket is cancelled to free up capacity for other users

Request Parameters

Name Required Type Description Example
reference Required String Capture reference received when availability was captured 32397D3E869EA04C71DD

Response

The response is an object containing the following properties.
Name Type Description Example
releasedReference String Capture reference which was released 32397D3E869EA04C71DD

Set capacity

POST/availabilities/{itemId}/priceCategories/{categoryId}

Sets capacity (number of available seats) for the item or for specific price category of the item

Request Parameters

Name Required Type Description Example
capacity Required Integer Capacity which is to be set for item or item price category 50
itemId Required String Id of the item 100681_trip_3b7db4ef28e335e5a6abf327b64b480c
ruleId Required Integer Rule id of the item, together with itemId it uniquely identifies an item 100681
categoryId Optional Integer Price category id for which capacity needs to be set. If omitted, capacity set for item in general 1554

Response

The response is an object containing the following properties.
Name Type Description Example
capacity Integer New capacity which was set by this request 50
old_capacity Integer Old capacity which was set prior to changing it 20
availabilityItemId String Id of the item change was applied to 100681_trip_3b7db4ef28e335e5a6abf327b64b480c
availabilityRuleId Integer Rule id of the item change was applied to 100681
priceCategoryId Integer Id of the price category (if any) the change was applied to. NULL is returned if change is applied to the item it general 1554

Availability Rules

Request Availability Rules

GET/availability-rules

Requests which availability rules are available

Request Parameters

Name Required Type Description
id Optional Array Filter for availability rule IDs. Could be one (or several) IDs. Multiple filters are possible
activityId Optional Array Filter for activity IDs. Could be one (or several) IDs. Multiple filters are possible
type Optional Array Availability types to filter for. Should be one (or several) of trip, day_trip, voucher
merchant Optional String Filter for merchant code. Could be one merchant.
outdated Optional Boolean Set this to true to include outdated availability rules in the result.
limit Optional Integer Limit
offset Optional Integer Offset

Response

The response is an object containing the following properties.
Name Type Description
id Integer Availability Rule ID
merchant String Merchant code
activityId Integer Activity ID
type String Type of activity
isActive Boolean Availability Rule status
name String Availability Rule Name
actualUntil String Rule Actual Date
duration String Duration
bookingNote String Booking Note
startDate String Departure Date
startTimes String Departure Times
recurrence Object Availability Rule recurrence settings
priceCategories Array Rule Price categories

Resources

Merchants List

GET/merchants

Gets a list of merchants

Request Parameters

Name Required Type Description
id Optional Array Filter for merchant IDs. Could be one (or several) IDs. Multiple filters are possible
slug Optional String Merchant code
language Optional String Filter for merchant language. If not provided, information in merchant's default language will be returned

Response

The response is an array of objects, each containing the following properties.
[{
    "id": 15873,
    "slug": "demo",
    "name": "Amazing Activities Demo",
    "address1": "1375 Broadway",
    "address2": null,
    "zip": "10018",
    "city": "New York",
    "country": "United States",
    "phone": "+41722222222",
    "publicEmail": "test@test.com",
    "supportedLanguages": [],
    "defaultLanguage": "nl",
    "language": "nl",
    "userFields": [
        {
            "code": "phone",
            "type": "phone",
            "isRequired": true,
            "label": "Phone Number",
            "options": ""
        },
        {
            "code": "language",
            "type": "select",
            "isRequired": true,
            "label": "Which Language do you prefer?",
            "options": [
                {
                    "key": "English",
                    "value": "English"
                },
                {
                    "key": "Spanish",
                    "value": "Spanish"
                },
                {
                    "key": "Italian",
                    "value": "Italian"
                }
            ]
        },
        {
            "code": "zip",
            "type": "text",
            "isRequired": false,
            "label": "Zipcode",
            "options": ""
        }, ...
    ],
    "defaultCurrency": "USD",
    "currencies": [
        "USD",
        "EUR",
        "GBP",
        "CHF",
        "NOK",
        "ZAR",
        "BRL",
        "HUF"
    ],
    "paymentGateways": [
        {
            "id": "42",
            "name": "TrekkSoft - TrekkPay"
        }
    ],
    "partnerCurrencies": [
        "EUR",
        "GBP",
        "CHF",
        "CAD",
        "AUD", ...
    ],
    "conversionRates": {
        "USD": 1,
        "EUR": 1,
        "GBP": 1.6312,
        "AUD": 0.7456, ...
    },
    "formats": {
        "shortDateTime": "d.m.Y H:i",
        "shortDate": "d.m.Y",
        "shortTime": "H:i"
    },
    "multiDiscounts": [
        0,
        4,
        10,
        12
    ],
    "timezone": "Europe/Berlin",
    "onlineBookingFee": 0.1
},
...
]
Name Type Description
id Integer Merchant ID
slug String Merchant code
name String Name
address1 String First line of the merchant's address
address2 String Second line of the merchant's address
zip String ZIP code of the merchant's address
city String City of the merchant
country String Country of the merchant
phone String Merchant's contact phone
publicEmail String Merchant's contact e-mail
language String Language of the merchant details
defaultLanguage String Default(primary) language of the merchant
supportedLanguages Array A list of languages supported by the merchant
timezone String Merchant's timezone
onlineBookingFee Float Merchant's online booking fee
userFields Array A list of extra details which users are required to fill in when making a booking with this merchant
userFields[0][code] String Internal code of the user field
userFields[0][label] String Label which should be shown for the field (in current language)
userFields[0][type] String Control type of the field. Possible options are
  • text - single line text field
  • textarea - multiline text field
  • radio - group of radio buttons
  • select - select box
  • date - datepicker
userFields[0][options] Array A list of options to select from for field types radio and select. NULL for other field types
userFields[0][options][0][key] String Option key (this should be sent to server when customer selects the option during booking process)
userFields[0][options][0][value] String Option value (this should be shown to the customer)
userFields[0][isRequired] Boolean Defines whether this field is required or optional
currencies[] Array Currencies which are supported by merchant in ISO4217 format (see https://en.wikipedia.org/wiki/ISO_4217 for more info)
paymentGateways Array List of payment gateways current merchant supports
paymentGateways[0][id] Integer Unique ID of a payment gateway
paymentGateways[0][name] String Name of a payment gateway
partnerCurrencies[] Array Currencies which are supported by merchant's partners in ISO4217 format (see https://en.wikipedia.org/wiki/ISO_4217 for more info)
defaultCurrency String Default currency of the merchant in ISO4217 format
conversionRates[] Array Conversion rates for this merchant from default currency
multiDiscounts Array Possible multi-discounts supported by this merchant
formats[] Array Various display formats specific to merchant (and his language!). For more info on date/time formats see http://php.net/manual/en/function.date.php
formats[shortDateTime] String Short date time
formats[shortDate] String Short date
formats[shortTime] String Short time

Mobile navigation groups

GET/merchants/{merchant_id}/mobilegroups

Returns a list of all navigation groups that are used on the mobile version of the website.

Request Parameters

Name Required Type Description
mandator_id Required Integer [url parameter] Unique numeric identifier of a merchant
order Optional String

One of the following:

  • sequenceIndex: By the defined sequence indexes.
  • near: By city closest to the position parameter
position Optional String Used with the order type near. Must be string separating a latitude and longitude with a comma

Response

The response is an array of objects, each containing the following properties.
Name Type Description
id Integer Unique numeric identifier of the tour group.
city String City associated with the tour group.
country_code String The 2-digit ISO country code of the tour group.
title String The title of the tour group.
url String The URL to the mobile page of the tour group.
sequence_index Integer Numeric number which is used to sort the tour groups. Groups with a lower sequence index should be displayed first.

Tickets

GET/ticket/validate/{code}

Validate ticket code

Request Parameters

Name Required Type Description
code Required String [url parameter] Ticket code to validate

Response

In case of successful ticket will be returned along with following details:
Name Type Description
valid Boolean Ticket status
bookingId Integer Booking ID
redemptions Array List of redemptions
redemptions[0][userId] Integer User ID
redemptions[0][userName] String User name
redemptions[0][userEmail] String User email
redemptions[0][createdAt] String Date of user creation
basketItem Object Basket item
basketItem[basketItemId] Integer Basket item
basketItem[activityId] Integer Activity ID
basketItem[activityTitle] String Activity title
basketItem[bookedAt] String Date of creation
basketItem[currency] String Basket currency code
guest Object Guest info
guest[id] Integer Guest ID
guest[name] String Guest name
guest[occupancy] Integer Occupancy
guest[price] String Price
guest[paymentStatus] String Payment status
guest[barCode] String Ticket code
guest[priceCategory] Object Price category
guest[priceCategory][id] String Price category ID
guest[priceCategory][name] String Price category name
In case of invalid ticket response contains only ticket status:
Name Type Description
valid Boolean Ticket status
In case it fails to authorize request, status 403 will be returned without any content

None.

Extras

Media Types

Custom media types are used in the API to allow developers choose the format and version of the data they wish to receive. This is done by adding one or more of the following types to the Accept header when sending a request. 

application/vnd.trekksoft[.version][+format]
application/json

As of v1 of the API the following Accept header is recommended:

application/vnd.trekksoft.v1+json, application/json; q=.5

Schema

All requests to the TrekkSoft API must be over HTTPS using the domain api2.trekksoft.com.

Example Request:

$ curl -i https://api2.trekksoft.com/

Example Response (to an unauthorized request):

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=UTF-8
Date: Mon, 10 Apr 2015 10:26:20 GMT

{}

All date fields are returned in RFC 3339 format:

YYYY-MM-DDTHH:MM:SSZ

Examples:

2012-12-24T15:39:15+02:00
2013-01-14T08:12:47-03:00

HTTP Verbs

The API makes use of the HTTP verbs to indicate what kind of request you are sending.

GET    /activities        Lists all resources of the 'activities' collection.
POST   /activities        Creates a new resource in the 'activities' collection.
PUT    /activities        Updates multiple resources in the 'activities' collection.
DELETE /activities        Deletes multiple resources in the 'activities' collection.
GET    /activities/435    Reads a resource from the 'activities' collection.
PUT    /activities/435    Updates a resource in the 'activities' collection.
DELETE /activities/435    Deletes a resource in the 'activities' collection.

Please note, that not every collection supports all HTTP verbs.

Time Periods

Some date fields support additional time period notation paramters. The following syntax is supported:

[PERIOD_START][,PERIOD_END]

2014-01-01T00:00:00+02:00                            # After/at 2014-01-01 00:00:00
2014-01-01T00:00:00+02:00,2014-01-31T23:59:59+02:00  # Between 2014-01-01 00:00:00
                                                     # and 2014-01-31 23:59:59
2014-01-31T23:59:59+02:00                            # Before/at 2014-01-31 23:59:59

Pagination

Requests that return multiple items are paginated to 30 items by default. Developers can control pagination by using the offset (default: 0) and limit (default: 30) query parameters. The custom limit may not exceed 100. 

GET /activities?offset=0&limit=20
GET /activities?offset=20&limit=20
GET /activities?offset=40&limit=20