NAV
shell

Introduction

Welcome to the Booking Experts API! If you're looking to integrate your application with data inside Booking Experts, you're in the right place. We are happy to have you!

The goal of these API's is to maximize collaboration between all parties involved in leisure. So in case you think that you miss some API's, please let us know by making an issue in Github.

For support questions you can reach out to connectivity@bookingexperts.nl.

Get access

To interact with one or more Booking Experts administrations you should become a Partner (which is free).

To get access please sign up as Partner. When you've signed up one of our colleagues will verify your sign up.

After the verification admin users can give you access to their administration(s). By default you will have access to all resources that are needed for making reservations.

You can request extended access for an administration which will allow you to access all resources for an administration. The access level is defined by an admin user of the administration.

Basics

The Booking Experts API is organized around REST and it tries to follow the JSON API specification were possible. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. JSON is returned by most API responses, including errors.

Versioning

Our API will always be backwards compatible using a never remove, only add strategy.

For future flexibility we prefix our endpoints with a version prefix.

Example: https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID

Some features are marked with experimental. This means that you can use them but the implementation will probably change.

Requests

All examples are shown using a command line tool called CURL. You should be able to copy and paste the commands in your shell. But before that make sure to set the following environment variables. Fetch: API_KEY, ADMIN_ID, ORGANIZATION_ID

export API_KEY=PASTE_YOUR_API_KEY
export ADMIN_ID=PASTE_ADMINISTRATION_ID
export ORG_ID=PASTE_ORGANIZATION_ID

To make a request for all categories in an administration it looks like

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/categories \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

After pasting a cURL example, you can pipe it to a JSON pretty printer to make it more readable. Try jsonpp or json_pp on OSX.

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/categories \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" | jsonpp

Authenticate your identity by including your secret API key in the request. You can manage your API key in the Partner Dashboard. Your API key carry many privileges, so be sure to keep them secret! Authentication to the API is performed via Token auth. All API requests must be made over HTTPS. Calls over HTTP or without Authentication will fail.

Responses

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/categories \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token invalid_api_key"

Produces the following output

{
  "errors": [
    {
      "status": 401,
      "title": "Unauthorized error",
      "detail": "Please make sure to set the Authorization HTTP header"
    }
  ]
}

The Booking Experts API will always respond with a HTTP status code. The API can return the following codes:

Code Semantic Meaning
200 OK Request was successful
400 Bad Request Parameters for the request are missing or malformed. Body contains the errors.
401 Unauthorized Your API key is wrong
403 Forbidden IP is blacklisted for API usage, see Throttling information
404 Not Found Entity not found
422 Unprocessable entity Saving the entity in the database failed due to validation errors. Body contains the errors.
429 Too Many Requests You're requesting too many kittens! Slow down!
5XX Server Errors Something went wrong on Booking Experts's end. We are probably already busy solving the issue. It's your responsibility to retry the request at a later point.

Accept language

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/groupings \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/groupings?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/groupings?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/groupings?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "groupings",
      "id": "1023",
      "attributes": {
        "name": {
          "nl": "Algemeen",
          "en": "General"
        },
        "position": 0
      }
    }
  ]
}

As you can see the translated name is returned in the languages set in the Accept-Language header

Translations can be fetched by setting an Accept-Language header. Available locales are:

Language Meaning
en English
nl Nederlands
fr Français
da Dansk
de Deutsch
cs Čeština

By default English translations are returned for translated attributes.

Pagination

{
  "links": {
    "first": "https://api.bookingexperts.nl/parks/388/categories?page%5Bnumber%5D=1",
    "prev": "https://api.bookingexperts.nl/parks/388/categories?page%5Bnumber%5D=2",
    "self": "https://api.bookingexperts.nl/parks/388/categories?page%5Bnumber%5D=3",
    "next": "https://api.bookingexperts.nl/parks/388/categories?page%5Bnumber%5D=4",
    "last": "https://api.bookingexperts.nl/parks/388/categories?page%5Bnumber%5D=5"
  },
  "data": [...]
}

All list actions include pagination. In the response body you will find a links node that contains links to first, self, next, prev, last pages. Most responses have 30 records per page.

Throttling

Usage of the Booking Experts API is virtually unlimited. However, to prevent fraud and abuse, requests to the API are throttled. By default you are allowed to call the API 500 times within a moving window of 15 minutes. Additionally, bursts of 100 calls per minute are allowed within this window.

While within the limit, each response contains a x-RateLimit-Limit and a x-RateLimit-Remaining header containing the set limit & the remaining allowance in the window.

If you exceed the limit, the API will respond with a 429 Too many requests response. This response contains a header Retry-After containing the time after which a new calls are allowed.

If your use case requires more lenient rate limits, please contact us to request a higher limit.

Field sets

By default every request returns a quite complete set of fields (attributes and relationships). You can limit or expand this default set however. Per record type you can specify which fields to include. There are 2 ways of using this feature:

Whitelist

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/categories?fields[categories]=name,short_description \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Will return only the name and short_description fields of every category.

Relative to default

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?fields[availabilities]=%2Bavailable_rentables,-checkin_time,-checkout_time" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

This will exclude the checkin and checkout time, and include the available_rentables (which is not included by default). Note the %2B before available rentables. That is the url encoding of '+'. Plusses need to url encoded, because otherwise a plus is considered a space when used in a url.

Accommodation subtypes

Sub categorization of a rental segment. For example, one could add a subtype like "Villa" for the rental segment "bungalow". Or "Glamping" for the rental segment "camping".

The accommodation subtype object

Attribute Meaning
name Translated name.

List all accommodation subtypes

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/accommodation_subtypes \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/accommodation_subtypes?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/accommodation_subtypes?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/accommodation_subtypes?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "accommodation_subtypes",
      "id": "100",
      "attributes": {
        "name": {
          "nl": "Villa",
          "en": "Villa"
        }
      }
    }
  ]
}

Returns a collection of all accommodation subtypes.

Administrations

Most resources are scoped under one administration. One organization can have multiple administrations. So there are some API calls that span multiple administrations. They can be found under the organization scope.

The administration object

Attribute Meaning
name Translated name.
description A translated description of the park.
surroundings_description A translated description of the surroundings of the park.
available_locales The locales (RFC 3066) that the administration supports.
max_baby_age Age until which a person is considered a baby.
max_child_age Age until which a person is considered a child.
max_adolescent_age Age until which a person is considered an adolescent.
min_senior_age Age from which a person is considered a senior.
group_details_required Whether or not the park requires guest group details to be supplied for new reservations.
option_allowed Whether or not the park allows options.
option_validity Amount of days an option will be valid. When an option expires it will be cancelled. 0 means that it's not possible to create options.
utc_offset UTC offset from the timezone of the administration.
same_day_booking_closing_time The time until a reservation can be made for today. 00:00 means that it's not possible to make reservations for today.

Retrieve an administration

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Returns details of an administration

Produces the following output

{
  "data": [
    {
      "type": "administrations",
      "id": "388",
      "attributes": {
        "name": {
          "en": "Holiday resort"
        },
        "max_baby_age": 1,
        "max_child_age": 11,
        "max_adolescent_age": 17,
        "option_allowed": false,
        "option_validity": 0,
        "utc_offset": "+01:00",
        "same_day_booking_closing_time": "00:00"
      },
      "relationships": {
        "city": {
          "data": {
            "type": "cities",
            "id": "2"
          }
        },
        "tags": {
          "data": [
            {
              "type": "tags",
              "id": "1476"
            }
          ]
        },
        "terms": {
          "data": {
            "type": "terms",
            "id": "166"
          }
        },
        "organization": {
          "data": {
            "type": "organizations",
            "id": "133"
          }
        }
      }
    }
  ]
}

List all administrations

Returns all administrations to which you have access

curl https://api.bookingexperts.nl/v1/administrations \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/administrations?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/administrations?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/administrations?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "administrations",
      "id": "388",
      "attributes": {
        "name": {
          "en": "Holiday resort"
        },
        "max_baby_age": 1,
        "max_child_age": 11,
        "max_adolescent_age": 17,
        "min_senior_age": 65,
        "option_allowed": false,
        "option_validity": 0,
        "utc_offset": "+01:00",
        "same_day_booking_closing_time": "00:00"
      },
      "relationships": {
        "city": {
          "data": {
            "type": "cities",
            "id": "2"
          }
        },
        "tags": {
          "data": [
            {
              "type": "tags",
              "id": "1476"
            }
          ]
        },
        "terms": {
          "data": {
            "type": "terms",
            "id": "166"
          }
        },
        "organization": {
          "data": {
            "type": "organizations",
            "id": "133"
          }
        }
      }
    }
  ]
}

Includes

You can include extra relations with this endpoint by adding an include parameter. Like this:

curl https://api.bookingexperts.nl/v1/administrations?include=city,city.region \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"
Include Object
city City
city.region Region
terms Terms
tags Tag

Area types

Represents an area such as "ground floor" or "first floor".

The area type object

Attribute Meaning
name Translated name
position Position used to display a sorted list.

List all area types

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/area_types \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/area_types?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/area_types?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/area_types?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "area_types",
      "id": "84",
      "attributes": {
        "name": {
          "en": "Ground floor"
        },
        "position": 0
      }
    }
  ]
}

Returns all area types

Availabilities

Availabilities represent a stay in an accommodation. It includes an exact (all-in) price for the supplied guest group and other filters. For example the search can give you a list of availabilities for 2 adults, 2 children, 1 pet, scoped on The Netherlands and Belgium with preference for an accommodation with sea view for a specific price range including all-in prices. This allows the guest to really compare accommodations because there will be no fees that are added during the reservation process.

Note: Users can explicitly exclude costs from the all-in price. This is not standard behaviour.

Note: It is also possible (and more efficient) to retrieve all availabilities for a particular category by using the category availabilities endpoint.

The availability object

Attribute Meaning
start_date Date of arrival.
los Length of stay in nights.
price All-in price considering rent, extras and discounts. Will be null when no guest group supplied.
original_price Price considering rent, extras but without discounts. Will be null when no guest group supplied.
rent_price Rent-only price. Does not include extra costs. Includes applicable discount.
original_rent_price Rent-only price without applicable discount.
checkin_time Time at from which the guest can checkin.
checkout_time Time at or before the guest should checkout.
stock The number of units of this category available in this period. Takes filters and allotments into account.

Relationships

Relationship Model
administration Administration
category Category
discount_campaign Discount campaign
missing_tags Tags. Only shown if using the tag_ids_match_score sorter
available_rentables Rentables. Excluded by default. Use field sets to include these.

Search availabilities

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?filter[start_date]=2017-08-01&filter[guest_group][adults]=2&limit[availabilities]=1" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Produces the following output

{
  "data": [
    {
      "type": "availabilities",
      "id": 21937190,
      "attributes": {
        "start_date": "2017-08-01",
        "los": 2,
        "price": 200.0,
        "original_price": 200.0,
        "rent_price": 120.0,
        "original_rent_price": 120.0,
        "checkin_time": "15:00",
        "checkout_time": "11:00",
        "stock": 1
      },
      "relationships": {
        "administration": {
          "data": {
            "type": "administrations",
            "id": "388"
          }
        },
        "category": {
          "data": {
            "type": "categories",
            "id": "5141"
          }
        }
      }
    }
  ]
}

Returns all matching availabities

Filters

To filter on start_date

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?filter[start_date]=2017-07-01" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

To filter on a range of start_dates

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?filter[start_date]=2017-07-01..2017-08-01" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

To filter on guest group

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?filter[guest_group][adults]=2" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

To filter on tags

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?filter[tag_ids]=1,2" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

To filter on attributes ranges (between 5 and 10 beds)

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?filter[attributes][beds]=5..10" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"
Filter Examples Meaning
start_date 2017-07-01, 2017-07-01..2017-07-02 Filter on start_date.
includes_date 2017-07-01, 2017-07-01..2017-07-02 Filter availabilities that contain all these dates. Note: date ranges have an exclusive end.
overlaps_date 2017-07-01, 2017-07-01..2017-07-02 Filter availabilities that (partially) overlap these dates. Note: date ranges have an exclusive end.
arrangement 2017-07-01..2017-08-01 Filter on availabilities that exactly match the supplied start- and end-date
los 2, 2..4 Filter on length of stay.
wday 0 Filter on a particular week day. 0 = sunday.
administration_ids 1,2 Filter on administrations.
category_ids 1,2,3 Filter on categories.
-category_ids 1,2,3 Exclude categories.
region_ids 1,2 Filter on regions.
-region_ids 1,2 Exlcude regions.
accommodation_subtype_ids 1,2 Filter on accommodation subtypes.
-accommodation_subtype_ids 1,2 Exclude accommodation subtypes.
rentale_segment_ids 1,2 Filter on rentable segments.
-rentable_segment_ids 1,2 Exclude rentable segments.
tag_ids 1,2 Filter on tags.
package_id 1 Filter on package.
discount_campaign_id 1 Filter on discount campaign.
country_codes NL,DE Filter on ISO 3166-1 alpha-2 country codes.
-country_codes NL,DE Exclude country codes.
rentable_types bungalow,apartment Filter on rentable types. DEPRECATED: use semantic_segments instead. Available types: bungalow, camping, hotelroom, berth, apartment, accommodation.
-rentable_types bungalow,apartment Exclude rentable types. DEPRECATED: use -semantic_segments instead.
semantic_segments bungalow,apartment Filter on semantic segments. Available types: bungalow, camping, hotelroom, berth, apartment, accommodation.
-semantic_segments bungalow,apartment Exclude semantic segments.
guest_group {adults: 2} Filter on guest group. Possible keys: seniors, adults, adolescents, children, babies, pets.
price 500.0..750.0 Filter on a price range.
currency USD Filter on a specific ISO 4217 currency code. By default the prices are returned in the administration's native currency. Results can differ per currency.
number_of_beds 2, 2..4 Filter on category number of beds.
number_of_child_beds 2, 2..4 Filter on category number of child beds.
number_of_child_chairs 2, 2..4 Filter on category number of child chairs.
number_of_showers 2, 2..4 Filter on category number of showers.
number_of_toilets 2, 2..4 Filter on category number of toilets.
number_of_bathrooms 2, 2..4 Filter on category number of bathrooms.
number_of_bedrooms 2, 2..4 Filter on category number of bedrooms.

Sorters

To sort on length of stay

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?sorters[0][type]=los" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

On price and start_date distance

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?sorters[0][type]=start_date_distance&sorters[0][start_date]=2017-07-01&sorters[1][type]=all_in_amount" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

On price descending (most expensive first)

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?sorters[0][type]=start_date_distance&sorters[0][start_date]=2017-07-01&sorters[1][type]=all_in_amount&sorters[1][desc]=true" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Configurable sorters. You can use multiple sorters in one request.

Sorter attributes

Attribute Meaning
type Specifies the type of sorter to use. A sorter may have more attributes to be specified depending on the type that is specified. See the examples below. Possible values: los, los_distance, start_date, start_date_distance, arrangement_distance, max_guests, highlighted, all_in_amount, tag_ids_match_score, avg_score.
desc Boolean (true/false), specifying the sort direction. When unspecified, ascending order is implied.

Sorter types

Sorter Query string example Meaning
los sorters[0][type]=los Order by length of stay (ascending or descending).
los_distance sorters[0][type]=los_distance&sorters[0][los]=7 Order by the distance of a particular length of stay (ascending or descending).
start_date sorters[0][type]=start_date Order by start dates (ascending or descending).
start_date_distance sorters[0][type]=start_date_distance&sorters[0][start_date]=2017-07-01 Order by the distance of a particular start date (ascending or descending).
arrangement_distance sorters[0][type]=arrangement_distance&sorters[0][arrangement]=2017-07-01..2017-07-08 Order by the distance of a particular arrangement (ascending or descending).
max_guests sorters[0][type]=max_guests Order by maximum guests of the category (ascending or descending).
highlighted sorters[0][type]=highlighted Order by availabilities that have a category that is highlighted (ascending or descending).
all_in_amount sorters[0][type]=all_in_amount Order by price (ascending or descending).
tag_ids_match_score sorters[0][type]=tag_ids_match_score&sorters[0][tag_ids]=1,2 Order by whether the tags match (ascending or descending).
avg_score sorters[0][type]=avg_score Order by average review score of the category (ascending or descending).

Pagination

To get 10 availabilities

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?limit[availabilities]=10" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

To get 10 availabilities for the 3 best categories

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?limit[availabilities_per_category]=10&limit[categories]=3" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

To get 10 availabilities for the 3 best arrival dates

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?limit[availabilities_per_start_date]=10&limit[start_dates]=3" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

To get 10 availabilities for the 3 best categories for the 2 best administrations

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?limit[availabilities_per_category]=10&limit[categories_per_administration]=3&limit[administrations]=2" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

This endpoint does not follow the json-api pagination guidelines because it does not fit our nested limits. We make use of a nested limit that makes it possible to for example show the 3 best categories for the 10 best administrations. This is especially when searching for accommodations (categories) over multiple holiday resorts (administrations). When a guest is searching for his perfect vacation the holiday resort is sometimes more important than the accommodation. In that case you might want to present the holiday resort to the guest with a summary of available accommodations (categories).

Limits

  1. availabilities
  2. availabilities_per_start_date
  3. availabilities_per_category
  4. start_dates
  5. categories
  6. categories_per_administration
  7. administrations

Offsets

We currently have support for limiting categories. This is our most common use case. You can paginate by offsetting using the limit[categories_offset] attribute.

Search alternatives

curl -g "https://api.bookingexperts.nl/v1/availabilities/search?filter[guest_group][adults]=2&sorters[][type]=arrangement_distance&sorters[][arrangement]=2017-11-11..2017-11-12&limit[availabilities_per_category]=1&limit[categories]=5" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

It's common that you want to search for alternatives when a query does not yield availabilities. Let me explain some of the important things to consider when querying for alternatives:

  1. Drop the filter on exact dates like the start_date and arrangement filters.
  2. Add the arrangement_distance sorter which will return results ordered by the distance of the arrangement which is (most of the time) exactly what you want.
  3. You (mostly) want a wide variate of results so in this example we limit for 5 categories and 1 availability per category.

Categories

A category represents a type of accommodation and thus can have multiple underlying accommodations. The specific accommodations are not advertised to the guest. Instead, we hide the exact accommodation from the guest so that the organization is flexible in assigning guests to different accommodations.

The category object

Attribute Meaning
name Translated name.
short_description Translated short description.
description Translated description formatted in HTML.
highlighted Whether this category should be presented with more emphasize.
reference Short reference code for the guest to communicate about this particular category with the organization.
rentable_type Rental segment of accommodations. DEPRECATED: use the rentable_segment relationship instead to retrieve the rentable segment of the category, and then use RentableSegment#semantic_segment. For example: bungalow, camping, hotelroom, berth, apartment, accommodation.
minimum_number_of_nights The minimum number of nights people need to book to be allowed to stay in this category.
max_number_of_people Total amount of people excluding babies that can be added to the reservation. null is considered unlimited.
max_number_of_babies Total amount of babies that can be added to the reservation. null is considered unlimited.
max_number_of_pets Total amount of pets that be added to the reservation. null is considered unlimited.
max_baby_age Threshold of what is considered a baby.
max_child_age Threshold of what is considered a child.
max_adolescent_age Threshold of what is considered an adolescent.
min_senior_age Threshold of what is considered a senior.
number_of_beds Amount of beds present in the accommodation. null is considered unknown.
number_of_child_beds Amount of child beds present in the accommodation. null is considered unknown.
number_of_child_chairs Amount of child chairs present in the accommodation. null is considered unknown.
number_of_showers Amount of showers present in the accommodation. null is considered unknown.
number_of_toilets Amount of toilets present in the accommodation. null is considered unknown.
number_of_bathrooms Amount of bathrooms present in the accommodation. null is considered unknown.
number_of_bedrooms Amount of bedrooms present in the accommodation. null is considered unknown.
pets_allowed all = all accommodations of this category allow pets, some = some accommodations of this category allow pets, none = pets are not allowed for all accommodations of this category.
host_image_url Image of the accommodation host.
last_date_with_price Last date that contains a price. After this date you know that it's not possible to book this category.
latitude Latitude of category location.
longitude Longitude of category location.
address Street and house number.
summer_youtube_id Youtube video ID that gives an impression of the summer.
winter_youtube_id Youtube video ID that gives an impression of the winter.
youtube_id Youtube video ID that gives a general impression.
usps Translated array of unique selling points.

A category also contains one link called website, which contains a URL to a page on the website of the organization that shows this category and allows the customer to book this category.

List all categories

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/categories \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/parks/388/categories?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/parks/388/categories?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/parks/388/categories?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "categories",
      "id": "5140",
      "links": {
        "website": "http://cms.bookingexperts.nl/booking_experts_router?location=show&organization_id=388&resource_id=5140&resource_type=category"
      },
      "attributes": {
        "name": {
          "nl": "Luxury villa for 12 persons",
          "en": null
        },
        "description": {
          "nl": "Our most luxurious accommodation directly at the waterfront.<br>Enjoy the beautiful sunset while dining with your family.<br><ul><li><strong>Waterfront</strong></li><li>Boat included</li><li>Free wi-fi</li></ul><br>",
          "en": null
        },
        "short_description": {
          "nl": "Located at the waterfront, boat is included",
          "en": null
        },
        "highlighted": false,
        "reference": "LUX-001",
        "semantic_segment": "bungalow",
        "max_number_of_people": 12,
        "max_number_of_babies": 0,
        "max_number_of_pets": 0,
        "max_baby_age": 1,
        "max_child_age": 11,
        "max_adolescent_age": 17,
        "min_senior_age": 65,
        "number_of_beds": 6,
        "number_of_child_beds": 1,
        "number_of_child_chairs": null,
        "number_of_showers": 4,
        "number_of_toilets": 2,
        "number_of_bathrooms": 2,
        "number_of_bedrooms": 2,
        "pets_allowed": "none",
        "host_image_url": null,
        "last_date_with_price": "2017-12-31",
        "latitude": 52.2086297,
        "longitude": 6.89072490000001,
        "address": "Het eeftink 11-12",
        "summer_youtube_id": null,
        "winter_youtube_id": null,
        "youtube_id": "Foi54om6oGQ",
        "usps": {
          "nl": ["Directly at the waterfront", "Boat included"],
          "en": null
        }
      },
      "relationships": {
        "rentable_segment": {
          "data": {
            "type": "rentable_segments",
            "id": "1"
          }
        },
        "city": {
          "data": {
            "type": "cities",
            "id": "2"
          }
        },
        "terms": {
          "data": {
            "type": "terms",
            "id": "1"
          }
        },
        "accommodation_subtype": {
          "data": {
            "type": "accommodation_subtypes",
            "id": "100"
          }
        },
        "images": {
          "data": [
            {
              "type": "images",
              "id": "48245"
            },
            {
              "type": "images",
              "id": "48246"
            }
          ]
        },
        "rooms": {
          "data": [
            {
              "type": "rooms",
              "id": "15160"
            }
          ]
        },
        "tags": {
          "data": [
            {
              "type": "tags",
              "id": "1477"
            },
            {
              "type": "tags",
              "id": "1476"
            }
          ]
        },
        "custom_attributes": {
          "data": [
            {
              "type": "custom_attributes",
              "id": "99792"
            },
            {
              "type": "custom_attributes",
              "id": "99791"
            }
          ]
        },
        "optional_tags": {
          "data": [
            {
              "type": "tags",
              "id": "1478"
            }
          ]
        },
        "extras": {
          "data": [
            {
              "type": "extras",
              "id": "invoice_item_template_1234"
            }
          ]
        },
        "costs": {
          "data": [
            {
              "type": "costs",
              "id": "invoice_item_template_12345"
            }
          ]
        }
      }
    }
  ]
}

Returns a list of all categories.

Includes

You can include extra relations with this endpoint by adding an include parameter. Like this:

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/categories?include=rentable_segment,tags \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Available includes are:

Include Model
rentable_segment Rentable segment
terms Terms
accommodation_subtype Accommodation subtype
images Image
city City
city.region Region
tags Tag
tags.grouping Grouping
custom_attributes Custom attribute
custom_attributes.grouping Grouping
rooms Room
rooms.area_type Area type
rooms.room_type Room type
rooms.tags Tag
rooms.tags.grouping Grouping
rooms.custom_attributes Custom attribute
rooms.custom_attributes.grouping Grouping
extras Extra
costs Cost

Category availabilities

Returns all availabilities for the given category, from today until approximately 1.5 year in the future, for all lengths of stay from 1 until 21 nights. Each availability includes the start date, length of stay, (base) rent amount, discounted rent amount, discount campaign ID (if a discount applies), stock, and whether or not the availability applies to guest groups with pets as well. More efficient than using the availabilities endpoint when retrieving the availabilities for a single category.

Note: this is a CSV endpoint, instead of a JSON endpoint, for data efficiency reasons

Note: this endpoint has support for the 304 Not Modified status code using the If-Modified-Since header.

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/categories/1/availabilities \
  -H "Accept: text/csv" \
  -H "Authorization: Token $API_KEY"

Produces the following output

start_date,los,rent_amount,discounted_rent_amount,discount_campaign_id,stock,available_for_pets
2019-08-15,2,40.00,32.00,4,1,0
2019-08-15,3,70.00,56.00,4,1,0
2019-08-15,4,100.00,80.00,4,1,0
2019-08-16,2,60.00,48.00,4,1,0

...

2021-02-13,18,180.00,144.00,4,5,1
2021-02-13,19,190.00,152.00,4,5,1
2021-02-13,20,200.00,160.00,4,5,1
2021-02-13,21,210.00,168.00,4,5,1

Category availability explanation

Attribute Meaning
start_date Date of arrival.
los Length of stay in nights.
rent_amount Rent-only price. Does not include extra costs or applicable discount.
discounted_rent_amount Rent-only price including applicable discount.
discount_campaign_id ID of the discount campaign that the applicable discount belongs to. May be empty.
stock The number of units of this category available in this period. Takes filters and allotments into account.
available_for_pets Whether or not any of the units of this category available in this period allow pets.

Cities

User defined city

The city object

Attribute Meaning
name Translated name.

Custom attributes

Custom attributes are used by categories and rooms to describe special attributes such as:

The custom attribute object

Attribute Meaning
name Translated name.
value Translated value, only set when requested in relation to categories.
position Position used to display a sorted list.
semantic_tag_type A computer readable type for the tag. See Semantic tag types for more information.
type Either a NumericalTag or MultipleChoiceTag.
custom_attribute_options Json object containing the options for the MultipleChoiceTag type, only included when the type is MultipleChoiceTag.

List all custom attributes

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/custom_attributes \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/custom_attributes?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/custom_attributes?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/custom_attributes?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "id": "1",
      "type": "custom_attributes",
      "attributes": {
        "name": {
          "nl": "Roken toegestaan",
          "en": "Smoking allowed"
        },
        "type": "MultipleChoiceTag",
        "position": 1,
        "semantic_tag_type": "smoking_allowed",
        "custom_attribute_options": [
          {
            "nl": "Ja",
            "en": "Yes"
          },
          {
            "nl": "Nee",
            "en": "No"
          }
        ]
      },
      "relationships": {
        "grouping": {
          "data": {
            "type": "groupings",
            "id": "4"
          }
        }
      }
    },
    {
      "id": "2",
      "type": "custom_attributes",
      "attributes": {
        "name": {
          "nl": "Aantal slaapkamers",
          "en": "Number of bedrooms"
        },
        "type": "NumericalTag",
        "position": 2,
        "semantic_tag_type": "other"
      },
      "relationships": {
        "grouping": {
          "data": {
            "type": "groupings",
            "id": "5"
          }
        }
      }
    }
  ]
}

Returns a list of all custom attributes

Includes

You can include extra relations with this endpoint by adding an include parameter. Like this:

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/tags?include=grouping \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Available includes are:

Include Model
grouping Groupings

Customer login requests

A customer login request is used to grant a customer access to the customer portal. A customer can manage all reservations of a organization in the customer portal.

Creating a customer login request

The http satus will indicate successful creation of the customer login request. An email will automatically be sent to the customer with a link to sign in to the customer portal.

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/customer_login_requests -d '
  {
    "email": "test@example.com"
  }' -X POST \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Discount campaigns

Discount campaigns are used to advertise discounts on rent prices for one or more categories. Discounts can be a percentage or a fixed amount.

The discount campaign object

Attribute Meaning
name Translated name.
description Translated description formatted as plain text.
rules Translated humanized rules that can be displayed to the guest to hint when the discount campaign will be applied.
rentable_type Rental segment of accommodations it can be used for. DEPRECATED: use the rentable_segment relationship instead to retrieve the rentable segment of the category, and then use RentableSegment#semantic_segment. For example: bungalow, camping, hotelroom, berth, apartment, accommodation.
image_url Image of this discount campaign.

The following attributes are not included by default, but can be included using field sets:

Attribute Meaning
start_date The start date of the discount campaign (may be today if the campaign is always valid)
minimum_stay_duration The minimum stay duration for a reservation to qualify for the discount campaign (in nights)

List all discount campaigns

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/discount_campaigns \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/nl/parks/388/discount_campaigns?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/nl/parks/388/discount_campaigns?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/nl/parks/388/discount_campaigns?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "discount_campaigns",
      "id": "1964",
      "attributes": {
        "name": {
          "nl": "Vroegboekkorting",
          "en": "Early bird"
        },
        "description": {
          "nl": "Boek vroeg en ontvang korting",
          "en": "Book early and get discounts!"
        },
        "rules": {
          "nl": [
            "Verblijf tussen 03-07-2017 en 04-09-2017 of",
            "Verblijf tussen 02-07-2018 en 03-09-2018",
            "Verblijf minimaal 7 nachten",
            "Reserveer vroeg, minimaal 90 dagen voor aankomst"
          ],
          "en": [
            "Stay between 2017-07-03 and 2017-09-04 or",
            "Stay between 2018-07-02 and 2018-09-03",
            "Stay at least 7 nights",
            "Book early, at least 90 days before arrival"
          ]
        },
        "image_url": {
          "original": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/header_lavender.jpg",
          "banner": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/banner_header_lavender.jpg",
          "large": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/large_header_lavender.jpg",
          "polaroid": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/polaroid_header_lavender.jpg",
          "thumb": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/thumb_header_lavender.jpg"
        }
      }
    },
    "relationships": {
      "rentable_segment": {
        "data": {
          "type": "rentable_segments",
          "id": "1"
        }
      }
    }
  ]
}

Returns a list of all discount campaigns.

List all global discount campaigns

Returns a list of discount campaigns that are in use in all administrations of this organization.

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/discount_campaigns/global \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/discount_campaigns/global?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/discount_campaigns/global?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/discount_campaigns/global?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "discount_campaigns",
      "id": "1964",
      "attributes": {
        "name": {
          "nl": "Vroegboekkorting",
          "en": "Early bird"
        },
        "description": {
          "nl": "Boek vroeg en ontvang korting",
          "en": "Book early and get discounts!"
        },
        "rules": {
          "nl": [
            "Verblijf tussen 03-07-2017 en 04-09-2017 of",
            "Verblijf tussen 02-07-2018 en 03-09-2018",
            "Verblijf minimaal 7 nachten",
            "Reserveer vroeg, minimaal 90 dagen voor aankomst"
          ],
          "en": [
            "Stay between 2017-07-03 and 2017-09-04 or",
            "Stay between 2018-07-02 and 2018-09-03",
            "Stay at least 7 nights",
            "Book early, at least 90 days before arrival"
          ]
        },
        "image_url": {
          "original": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/header_lavender.jpg",
          "banner": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/banner_header_lavender.jpg",
          "large": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/large_header_lavender.jpg",
          "polaroid": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/polaroid_header_lavender.jpg",
          "thumb": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/thumb_header_lavender.jpg"
        }
      }
    },
    "relationships": {
      "rentable_segment": {
        "data": {
          "type": "rentable_segments",
          "id": "1"
        }
      }
    }
  ]
}

Includes

You can include extra relations with this endpoint by adding an include parameter. Like this:

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/discount_campaigns?include=rentable_segment \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Available includes are:

Include Model
rentable_segment Rentable segment

Discount cards

Discount cards implicitly represent a package, usually with a custom price per night or a discount depending on the time of stay.

The discount card object

Attribute Meaning
name Translated name.
description Translated description formatted as plain text.
image_url Image of this discount card (optional)

List all discount cards

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/discount_cards \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/nl/parks/388/discount_cards?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/nl/parks/388/discount_cards?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/nl/parks/388/discount_cards?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "discount_cards",
      "id": "1964",
      "attributes": {
        "name": {
          "nl": "ACSI",
          "en": "ACSI"
        },
        "description": {
          "nl": "Boek met uw ACSI kaart.",
          "en": "Book with your ACSI card."
        },
        "image_url": {
          "original": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_card/1964/header_lavender.jpg",
          "banner": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_card/banner/1964/banner_header_lavender.jpg",
          "thumb": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_card/thumb/1964/thumb_header_lavender.jpg"
        }
      }
    }
  ]
}

Extras

The extras object

An extra is an option that can be added to a reservation.

Attribute Meaning
name Translated name
description Translated description
invoiced_as Translated name under which this extra is invoiced
selectable Either 'customer' or 'important'. Important extras should be added to the chosen extras by default (opt-out)
available_for_customer Either 'always, during_booking or during_upgrade'.
quantity_required Whether or not a quantity is required when this extra is chosen
memo_required Whether or not a memo is required when this extra is chosen
memo_description A translated question that should be asked when this extra is chosen, of which the answer should be in the memo
maximum_quantity The maximum allowed quantity (may be empty, in case there is no maximum)
image_url An optional image URL hash with different versions
extra_type While the exact name of an extra can be chosen by the park itself, this type will make sure both parties know what this extra actually represents, and will be specified for the most common extras. See types. Note that not all extras will have an extra_type: it can also be null.

Extras as part of reservations have these additional attributes:

Attribute Meaning
price The price of this extra

Extras as part of a category or retrieved using the extras endpoint have these additional attributes to determine when they can be added to a reservation, and what the price will be:

Attribute Meaning
require_stay_overlaps Array of periods. The extra can only be applied if the stay overlaps any of the periods
require_booking_in Array of periods. The extra can only be applied on the days in the periods
amounts Array of amounts. These determine how the price of the extra is calculated from a reservation and it's other costs and extras

An extra can be added to a reservation if all 'require_' conditions are met and if it is in the category's 'extras' relationship.

Extra / Cost types

The following types exist right now. Please be aware that we can choose to add new ones at any time.

List all extras

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/extras \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "data": [
    {
      "type": "extras",
      "id": "invoice_item_template_1234",
      "attributes": {
        "require_stay_overlaps": [[null, "2020-01-01"]],
        "require_booking_in": [["2018-01-01", "2020-01-01"], ["2020-03-01", null]],
        "amounts": [
          {
            "type": "per_day",
            "prices": [ 3.0 ],
            "class": "extras"
          }
        ],
        "name": {
          "en": "Extra tent",
          "nl": "Bijzettent/partytent ( max. 2x2 m.)"
        },
        "invoiced_as": {
          "en": "Tent",
          "nl": "Tent"
        },
        "selectable": "customer",
        "quantity_required": false,
        "memo_required": false,
        "maximum_quantity": 1
      }
    },
    {
      "type": "extras",
      "id": "invoice_item_template_12345",
      "attributes": {
        "amounts": [
          {
            "type": "per_piece",
            "prices": [ 4.5 ],
            "class": "extras"
          }
        ],
        "name": {
          "en": "Towel set",
          "nl": "Handdoekenpakket"
        },
        "invoiced_as": {
          "en": "Towel set",
          "nl": "Handdoekenpakket"
        },
        "description": {
          "en": "3 towels.",
          "nl": "Dit pakket bestaat uit 3 handdoeken."
        },
        "selectable": "customer",
        "quantity_required": true,
        "memo_required": false,
        "maximum_quantity": 20
      }
    },
    {
      "type": "extras",
      "id": "package_123",
      "attributes": {
        "amounts": [
          {
            "type": "fixed",
            "prices": [ 5.0 ],
            "class": "extras"
          },
          {
            "type": "percentage",
            "percentages": [ 5.5 ],
            "over_classes": [ "rent" ]
          }
        ],
        "name": {
          "en": "Cancellation insurance",
          "nl": "Annuleringsfonds"
        },
        "invoiced_as": {
          "en": "Cancellation insurance",
          "nl": "Annuleringsfonds"
        },
        "selectable": "customer",
        "quantity_required": false,
        "memo_required": false,
        "maximum_quantity": 1,
        "image_url": {
          "original": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/header_lavender.jpg",
          "banner": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/banner_header_lavender.jpg",
          "large": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/large_header_lavender.jpg",
          "polaroid": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/polaroid_header_lavender.jpg",
          "thumb": "https://be-development.s3.eu-central-1.amazonaws.com/uploads/discount_campaign/banner/1964/thumb_header_lavender.jpg"
        }
      }
    }
  ]
}

Returns a list of all extras.

Costs

The costs object

A cost is a surcharge that may apply on a certain reservation. You can use the costs endpoint & the costs relation of categories to determine the price of a reservation without calling the API for a reservation preview. This also allows you to calculate the price of any extras that may apply to the reservation.

Attribute Meaning
name Translated name
description Translated description
invoiced_as Translated name under which this cost is invoiced
if_stay_overlaps DEPRECATED. Replaced by if_stay_starts_in. A cost should only apply if the stay actually starts in any of its periods, not if it overlaps.
if_stay_starts_in Array of periods. The cost will only be applied if the stay starts in any of the periods. If this attribute is not set, the cost always applies.
amounts Array of amounts. These determine what the price of the cost will be, as a function of the reservation and the costs and other extras
cost_type While the exact name of an extra can be chosen by the park itself, this type will make sure both parties know what this extra actually represents, and will be specified for the most common extras. See types. Note that not all extras will have an extra_type: it can also be null.

A cost will be added to a reservation if it matches the 'if_stay_starts_in' condition and if it is in the category's 'costs' relationship.

Cost / Extra types

The following types exist right now. Please be aware that we can choose to add new ones at any time.

List all costs

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/costs \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "data": [
    {
      "type": "costs",
      "id": "invoice_item_template_1234",
      "attributes": {
        "name": {
          "nl": "Huisdier",
          "en": "Pet"
        },
        "invoiced_as": {
          "nl": "Huisdier",
          "en": "Pet"
        },
        "amounts": [
          {
            "type": "per_guest_per_day",
            "prices": [ 7.5, "2020-01-01", 8.5],
            "class": "rent",
            "counts_guests": [ "pets" ]
          }
        ]
      }
    },
    {
      "type": "costs",
      "id": "invoice_item_template_12345",
      "attributes": {
        "name": {
          "nl": "Schoonmaakkosten",
          "en": "Cleaning costs"
        },
        "invoiced_as": {
          "nl": "Bijkomende kosten",
          "en": "Additional costs"
        },
        "if_stay_starts_in": [[null, "2020-01-01"]],
        "amounts": [
          {
            "type": "fixed",
            "prices": [ 12.5 ],
            "class": "defaults"
          }
        ]
      }
    },
    {
      "type": "costs",
      "id": "invoice_item_template_123456",
      "attributes": {
        "name": {
          "nl": "Toeristenbelasting",
          "en": "Tourist tax"
        },
        "invoiced_as": {
          "nl": "Bijkomende kosten",
          "en": "Additional costs"
        },
        "if_stay_starts_in": [[null, "2020-01-01"]],
        "amounts": [
          {
            "type": "per_guest_per_day",
            "prices": [ 1.25 ],
            "class": "defaults",
            "counts_guests": [ "seniors", "adults", "adolescents", "children" ]
          }
        ]
      }
    }
  ]
}

Returns a list of all costs.

Amounts

Example: an amount per pet, with two price overrides for the categories with IDs 123 and 456, respectively.

{
  "type": "per_guest_per_day",
  "prices": [ 7.5, "2020-01-01", 8.5],
  "category_price_overrides": {
    "123": [ 7.0, "2020-01-01", 8.0 ],
    "456": [ 8.0, "2020-01-01", 8.5 ]
  },
  "class": "rent",
  "counts_guests": [ "pets" ]
}

Example: a percentage over rent and non-rent default costs, with two percentage overrides for the categories with IDs 123 and 456, respectively.

{
  "type": "percentage",
  "percentages": [ 5.5, "2020-01-01", 5.55],
  "category_percentage_overrides": {
    "123": [ 6.0, "2020-01-01", 6.1 ],
    "456": [ 5.0, "2020-01-01", 5.1 ]
  },
  "over_classes": [ "rent", "defaults" ]
}

An amount represents a price component of a cost or extra, and how it's calculated from a reservation and it's other costs and extras. It is represented as a hash with a key type, that denotes how it's calculated, and some other attributes, that define the parameters for the calculation. An amount may have price (or percentage) overrides for certain categories. If overrides are listed for certain categories, these should be used when determining the costs or extras for those categories, instead of the regular prices/percentages.

Attribute For type Meaning
type - One of fixed, per_piece, per_guest, per_guest_per_day, percentage
prices fixed, per_piece, per_guest, per_guest_per_day The price parameter for the calculation over time. Represented as follows: [<initial price>, <price change date>, <new price>, ...].
category_price_overrides fixed, per_piece, per_guest, per_guest_per_day Optional price overrides for certain categories. Each price override is a mapping of a category ID to the set of prices that should be used for that category, instead of the default prices. Represented as follows: { "<category ID>": [<initial price>, <price change date>, ...], ... }.
class fixed, per_piece, per_guest, per_guest_per_day The class to which the amount belongs. This is relevant for the calculation of percentage prices.
counts_guests per_guest, per_guest_per_day The types of guests counted for the guests parameter of the calculation. An array containing a subset of ['seniors', 'adults', 'adolescents', 'children', 'babies', 'pets'].
counts_from per_guest, per_guest_per_day Count guests from X. For example: if counts_guests = ['adults'] and counts_from = 2 and there is a reservation with 3 adults, it will effectively count 1.
counts_to per_guest, per_guest_per_day Count guests till Y. For example: if counts_guests = ['adults'] and counts_to = 3 and there is a reservation with 4 adults, it will effectively count 3. If there is also a counts_from = 1, then it will still be 3.
percentages percentage The percentage parameter for the calculation over time. Represented as follows: [<initial percentage> <percentage change date>, <new percentage>, ...].
category_percentage_overrides percentage Optional percentage overrides for certain categories. Each percentage override is a mapping of a category ID to the set of percentages that should be used for that category, instead of the default percentages. Represented as follows: { "<category ID>": [<initial percentage> <percentage change date>, ...], ... }.
over_classes percentage The classes of price components over which this percentage is calculated. The total_of_over_classes parameter for the calculation is the total of all price components that have a class that is in this array.

The price of the various types of amounts is calculated as follows:

Type Calculation
fixed effective_price
per_piece effective_price * quantity
per_guest effective_price * guests
per_guest_per_day effective_price * guests * los
percentage effective_percentage * total_of_over_classes

Here, effective_price is the price that applies to the category, i.e., either the default price, or the price given by a price override for that category (if any). A similar reasoning applies for effective_percentage.

Periods

Example: normal period

["2020-01-01", "2020-01-30"]

Example: period from the beginning of time to 1 jan 2020

[null, "2020-01-30"]

Periods are represented as an array with two values: [<start>, <end>]. If <start> or <end> is nil, the period is not limited in that direction. The period includes all dates greater then or equal to <start>, and less then <end>.

Groupings

Has many tags and custom attributes. Is used to group a set of tags and custom attributes.

The grouping object

Attribute Meaning
name Translated name.
position Position used to display a sorted list.

List all groupings

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/groupings \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/groupings?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/groupings?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/groupings?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "groupings",
      "id": "1023",
      "attributes": {
        "name": {
          "nl": "Algemeen",
          "en": "General"
        },
        "position": 0
      }
    },
    {
      "type": "groupings",
      "id": "1021",
      "attributes": {
        "name": {
          "nl": "Badkamer",
          "en": "Bathroom"
        },
        "position": 1
      }
    }
  ]
}

Returns a list of all room types

Images

Images as part of categories. The extension will be jpg, png or gif.

The image object

Attribute Meaning
position Position used to display a sorted list.
season Relevance for stays during summer, winter or whole year.
image_url Hash with image versions. See image versions.

Image versions

Most image_url attributes contain the following versions.

Version Size
original_url Original image file.
banner Image file resized to fill 1600x506.
large Image file resized to fit 800x600.
polaroid Image file resized to fill 400x300.
thumb Image file resized to fill 105x60.

Invoice items

Invoice items as part of reservations.

The invoice item object

Attribute Meaning
name Translated name
type The type of the item, one of: cost (to be paid on arrival), cost_down (to be paid as part of the downpayment), deposit (to be paid as part of a deposit) or provision (part of the provision)
quantity Quantity of the item, if applicable
quantity_type The quantity type, see quantity types
display_quantity_type A translated, humanized value for the item's quantity type
price The total price of the item
in_advertised_price When true, the item is part of the specified all-in price
product_name A static name for the product. This is usually of the format ' - ' in English.
sku The product code
invoiced_to The party that gets the invoice for this item. Can be tour_operator or customer. When the tour operator handles the payment of the customer, this is normally set to tour_operator.

Quantity types

An invoice item can have one of the following quantity types:

Quantity type Meaning
fixed Per stay
per_day Per day
per_person Per person
per_person_per_day Per person per day
per_pet Per pet
per_pet_per_day Per pet per day
per_piece Per piece
per_piece_per_day Per piece per day
percentage_over_rent A percentage of the rent (including discounts)
percentage_over_total A percentage of the total price
percentage_over_default_extras A percentage of the default rent and required costs
percentage_over_default_rent A percentage of the default rent (including discounts)

Maps

Yields a map with free rentables of the given category for the given criteria.

The map object

Attribute Meaning
tile_layer The tile layer template for use in (for example) a Leaflet map
max_zoom_level Returns the maximum zoom level available for this map
width The width of the map (in pixels)
height The height of the map (in pixels)
geo_json GeoJSON data (https://tools.ietf.org/html/rfc7946) containing all mapped rentables. Features will have an ID matching the map_identifier of a rentable

Retrieve a map

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/categories/123/map?locale=nl&currency=EUR&start_date=2017-08-18&end_date=2017-08-25&include=available_rentables \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "data": {
    "type": "maps",
    "id": "4726",
    "attributes": {
      "tile_layer": "https://be-development.s3.eu-central-1.amazonaws.com/maps/307/{z}/map_tile_{x}_{y}.png",
      "max_zoom_level": 4,
      "width": 3507,
      "height": 2480,
      "geo_json": {
        "type": "FeatureCollection",
        "features": [
          {
            "geometry": {
              "type": "Point",
              "coordinates": [
                82.5,
                -56.876953125
              ]
            },
            "properties": {
              "id": "rentable-9232",
              "radius": 1.42521928137392
            },
            "type": "Feature"
          },
          {
            "geometry": {
              "type": "Point",
              "coordinates": [
                86.375,
                -56.001953125
              ]
            },
            "properties": {
              "id": "rentable-9233",
              "radius": 1.352081728299
            },
            "type": "Feature"
          }
        ]
      }
    },
    "relationships": {
      "available_rentables": {
        "data": [
          {
            "type": "rentables",
            "id": "35268"
          },
          {
            "type": "rentables",
            "id": "35269"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "rentables",
      "id": "35268",
      "attributes": {
        "name": "2psd-1",
        "map_identifier": "rentable-9232",
        "preference_costs": 0,
        "pets_allowed": true
      },
      "relationships": {
        "tags": {
          "data": [
            {
              "type": "tags",
              "id": "1478"
            },
            {
              "type": "tags",
              "id": "1479"
            }
          ]
        }
      }
    },
    {
      "type": "rentables",
      "id": "35269",
      "attributes": {
        "name": "2psd-2",
        "map_identifier": "rentable-9233",
        "preference_costs": 500,
        "pets_allowed": true
      }
    }
  ]
}

Includes

Available includes are:

Include Model
available_rentables Rentables
available_rentables.tags Tag
available_rentables.images Image

Options

Options are similar to reservations but they differ in that the guest has some days to confirm the option.

The option object

Please have a look at the reservation object because the object itself is similar.

Option includes

You can include extra relations to the endpoints by adding an include parameter. Like this:

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/options/911610?include=category.terms&token=f42604ea8bdd573fc279dfb8905ea9626ae3991a \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Available includes are:

Include Model
available_extras Extras
category Category
invoice_items Invoice item
package Package
rentable Rentable
tags Tag

Retrieve an option

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/options/911610?include=tags,available_extras,invoice_items&token=f42604ea8bdd573fc279dfb8905ea9626ae3991a \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Returns

{
  "data": {
    "type": "options",
    "id": 911610,
    "links": {},
    "attributes": {
      "status": "placed",
      "token": "f42604ea8bdd573fc279dfb8905ea9626ae3991a",
      "start_date": "2017-08-01",
      "checkin_time": "15:00",
      "checkout_time": "11:00",
      "end_date": "2017-08-08",
      "currency": "EUR",
      "guest_group": {
        "seniors": 0,
        "adults": 2,
        "adolescents": 0,
        "children": 0,
        "babies": 0,
        "pets": 0
      },
      "chosen_extras": [
        {
          "extra_id": "invoice_item_template_18719",
          "memo": "My child is 1.80m, will he fit?",
          "quantity": 5
        }
      ],
      "title": "mr",
      "first_name": "Ruud",
      "last_name": "Seydel",
      "date_of_birth": "1989-01-25",
      "email": "ruud@bookingexperts.nl",
      "phone": "0881168901",
      "address": "Het eeftink",
      "number": "11-12",
      "postalcode": "7541WH",
      "city": "Enschede",
      "country_code": "NL",
      "is_company": true,
      "company": "Booking Experts B.V.",
      "vat_nr": "NL851863681B01",
      "has_custom_invoice_details": true,
      "debtor": {
        "name": "Ali Ilboga",
        "email": "billing@bookingexperts.nl",
        "address": "Het Eeftink 11-12",
        "postalcode": "7541WH",
        "city": "Enschede",
        "country_code": "NL"
      },
      "receive_newsletter": true,
      "traffic_source_options": [
        {
          "id": 205668,
          "label": "Vakantiebeurs"
        }
      ],
      "traffic_source": null,
      "labels": ["local", "vandal"],
      "total": 7014.0,
      "deposit": 0.0,
      "rent": 7000.0,
      "provision": 700.0,
      "invoice_details": null,
      "after_payment_return_url": null,
      "payment_plan_options": [
        {
          "id": "total",
          "price": 7014.0
        }
      ],
      "payment_plan": "total",
      "questions_completed": false,
      "deposit_completed": false,
      "coupon_allowed": false,
      "coupon": null,
      "group_details_required": false
    },
    "relationships": {
      "category": {
        "data": {
          "type": "categories",
          "id": "5140"
        }
      },
      "invoice_items": {
        "data": [
          {
            "type": "invoice_items",
            "id": "invoice_item_8717406"
          },
          {
            "type": "invoice_items",
            "id": "invoice_item_8717407"
          }
        ]
      },
      "available_extras": {
        "data": [
          {
            "type": "extras",
            "id": "invoice_item_template_18719"
          },
          {
            "type": "extras",
            "id": "package_437"
          }
        ]
      },
      "tags": {
        "type": "tags",
        "id": "1476"
      }
    }
  },
  "included": [
    {
      "type": "tags",
      "id": "1476",
      "attributes": {
        "name": {
          "nl": "Gratis Wi-Fi",
          "en": "Free Wi-Fi"
        },
        "search": false,
        "highlight": false,
        "position": 0,
        "scheme_attribute": "wifi"
      },
      "relationships": {
        "groupings": {
          "data": {
            "type": "groupings",
            "id": "1023"
          }
        }
      }
    },
    {
      "type": "extras",
      "id": "invoice_item_template_18719",
      "attributes": {
        "name": {
          "nl": "Kinderbed",
          "en": "Child's bed"
        },
        "description": {
          "nl": "Korte omschrijving",
          "en": "Short description"
        },
        "quantity_required": false,
        "memo_required": false,
        "memo_description": null,
        "price": 14.0,
        "maximum_quantity": 2,
        "image_url": null
      }
    },
    {
      "type": "extras",
      "id": "package_437",
      "attributes": {
        "name": {
          "nl": "Sauna arrangement",
          "en": "Sauna package"
        },
        "description": {
          "nl": "Dit is een HTML opgemaakte tekst over <strong>Sauna</strong>",
          "en": "This is a text in HTML markup about <strong>Sauna</strong>"
        },
        "quantity_required": false,
        "memo_required": false,
        "memo_description": null,
        "price": 215.0,
        "maximum_quantity": 1,
        "image_url": null
      }
    },
    {
      "type": "invoice_items",
      "id": "invoice_item_8717406",
      "attributes": {
        "name": {
          "nl": "Huur",
          "en": "Rent"
        },
        "quantity": 1.0,
        "price": 7000.0,
        "type": "cost_down",
        "in_advertised_price": true,
        "product_name": "Rent - Luxury villa for 12 persons",
        "sku": "rent_5140",
        "quantity_type": "Per verblijf"
      }
    },
    {
      "type": "invoice_items",
      "id": "invoice_item_8717407",
      "attributes": {
        "name": {
          "nl": "Kinderbed",
          "en": "Child's bed"
        },
        "quantity": 5.0,
        "price": 14.0,
        "type": "cost_down",
        "in_advertised_price": true,
        "product_name": "Cot",
        "sku": "extra_cost_18719",
        "quantity_type": "Per verblijf"
      }
    }
  ]
}

Returns the details of an option

Preview an option

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/options/preview?include=invoice_items -d '
  {
    "data": {
      "type": "options",
      "attributes": {
        "start_date": "2017-08-01",
        "end_date": "2017-08-08",
        "guest_group": {
          "adults": 2
        },
        "currency": "EUR"
      },
      "relationships": {
        "category": {
          "data": {
            "type": "categories",
            "id": "5140"
          }
        },
        "tags": {
          "data": [{
            "type": "tags",
            "id": 1476
          }]
        }
      }
    }
  }' -X POST \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Returns

{
  "data": {
    "type": "options",
    "id": null,
    "attributes": {
      "start_date": "2017-08-01",
      "checkin_time": "15:00",
      "checkout_time": "11:00",
      "end_date": "2017-08-08",
      "currency": "EUR",
      "guest_group": {
        "seniors": 0,
        "adults": 2,
        "adolescents": 0,
        "children": 0,
        "babies": 0,
        "pets": 0
      }
    },
    "relationships": {
      "category": {
        "data": {
          "type": "categories",
          "id": "5140"
        }
      },
      "invoice_items": {
        "data": [
          {
            "type": "invoice_items",
            "id": "a7edd2772560f17fb5e0"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "invoice_items",
      "id": "a7edd2772560f17fb5e0",
      "attributes": {
        "name": {
          "nl": "Huur",
          "en": "Rent"
        },
        "quantity": 1.0,
        "price": 7000.0,
        "type": "cost_down",
        "in_advertised_price": true,
        "product_name": "Rent - Luxury villa for 12 persons",
        "sku": "rent_5140",
        "quantity_type": "Per verblijf"
      }
    }
  ]
}

Returns a preview which includes prices and included extra's. This can be used to give the guest an idea of how the total price is composed. You can you the same attributes as for creating a option.

Validate an option

curl "https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/options/validate" -d '
  {
    "data": {
      "type": "options",
      "attributes": {
        "start_date": "2017-08-01",
        "end_date": "2017-08-08",
        "guest_group": {
          "adults": 2
        },
        "currency": "EUR"
      },
      "relationships": {
        "category": {
          "data": {
            "type": "categories",
            "id": "5140"
          }
        },
        "tags": {
          "data": [{
            "type": "tags",
            "id": 1476
          }]
        }
      }
    }
  }' -X POST \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Returns

{
  "errors": [
    {
      "status": 422,
      "title": "Save resource failed",
      "detail": "can't be blank",
      "source": "attributes/first_name"
    },
    {
      "status": 422,
      "title": "Save resource failed",
      "detail": "can't be blank",
      "source": "attributes/postalcode"
    },
    {
      "status": 422,
      "title": "Save resource failed",
      "detail": "can't be blank",
      "source": "attributes/email"
    },
    {
      "status": 422,
      "title": "Save resource failed",
      "detail": "can't be blank",
      "source": "attributes/phone"
    },
    {
      "status": 422,
      "title": "Save resource failed",
      "detail": "can't be blank",
      "source": "attributes/date_of_birth"
    }
  ]
}

Similar to the preview action, but will return a list of errors when the passed in option is not valid. Otherwise, it will return a preview which includes prices and included extra's.

Create an option

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/options?include=rentable,invoice_items -d '
  {
    "data": {
      "type": "options",
      "attributes": {
        "start_date": "2017-10-06",
        "end_date": "2017-10-13",
        "guest_group": {
          "adults": 2
        },
        "currency": "EUR",
        "title": "mr",
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1983-11-05",
        "email": "info@bookingexperts.nl",
        "phone": "0647778135",
        "address": "Het eeftink",
        "number": "11-12",
        "city": "Enschede",
        "postalcode": "7541WH",
        "country_code": "NL",
        "receive_newsletter": true,
        "is_company": true,
        "company": "Booking Experts B.V.",
        "vat_nr": "NL851863681B01",
        "has_custom_invoice_details": true,
        "debtor": {
          "name": "Ali Ilboga",
          "email": "billing@bookingexperts.nl",
          "address": "Het Eeftink 11-12",
          "postalcode": "7541WH",
          "city": "Enschede",
          "country_code": "NL"
        }
      },
      "relationships": {
        "rentable": {
          "data": {
            "type"=>"rentables",
            "id"=>"35269"
          }
        },
        "category": {
          "data": {
            "type": "categories",
            "id": "4726"
          }
        },
        "tags": {
          "data": [{"id": "286", "type": "tags"}, {"id": "296", "type": "tags"}]
        }
      }
    }
  }' -X POST \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Returns

{
  "data": {
    "type": "options",
    "id": "926494",
    "links": {},
    "attributes": {
      "status": "placed",
      "token": "74cda7711a1fd6f4fcf950d4e0ea0b26513f8813",
      "start_date": "2017-10-06",
      "checkin_time": "15:00",
      "checkout_time": "11:00",
      "end_date": "2017-10-13",
      "currency": "EUR",
      "guest_group": {
        "seniors": 0,
        "adults": 2,
        "adolescents": 0,
        "children": 0,
        "babies": 0,
        "pets": 0
      },
      "title": "mr",
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1983-11-05",
      "email": "info@bookingexperts.nl",
      "phone": "0647778135",
      "address": "Het eeftink",
      "number": "11-12",
      "postalcode": "7541WH",
      "city": "Enschede",
      "country_code": "NL",
      "is_company": true,
      "company": "Booking Experts B.V.",
      "vat_nr": "NL851863681B01",
      "has_custom_invoice_details": true,
      "debtor": {
        "name": "Ali Ilboga",
        "email": "billing@bookingexperts.nl",
        "address": "Het Eeftink 11-12",
        "postalcode": "7541WH",
        "city": "Enschede",
        "country_code": "NL"
      },
      "receive_newsletter": false,
      "traffic_source_options": [],
      "traffic_source": null,
      "labels": [],
      "total": 362.0,
      "deposit": 0.0,
      "rent": 356.0,
      "provision": 0.0,
      "invoice_details": null,
      "has_rentable_map": true,
      "after_payment_return_url": null,
      "payment_plan_options": [
        {
          "id": "total",
          "price": 0
        }
      ],
      "payment_plan": "total",
      "questions_completed": false,
      "deposit_completed": false,
      "coupon_allowed": false,
      "coupon": null,
      "group_details_required": false
    },
    "relationships": {
      "category": {
        "data": {
          "type": "categories",
          "id": "4726"
        }
      },
      "rentable": {
        "data": {
          "type": "rentables",
          "id": "35269"
        }
      },
      "tags": {
        "data": [
          {
            "type": "tags",
            "id": "286"
          },
          {
            "type": "tags",
            "id": "296"
          }
        ]
      },
      "invoice_items": {
        "data": [
          {
            "type": "invoice_items",
            "id": "invoice_item_8812189"
          },
          {
            "type": "invoice_items",
            "id": "invoice_item_8812190"
          }
        ]
      },
      "available_extras": {
        "data": [
          {
            "type": "extras",
            "id": "invoice_item_template_18118"
          },
          {
            "type": "extras",
            "id": "invoice_item_template_18849"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "rentables",
      "id": "35269",
      "attributes": {
        "name": "2psd-2",
        "map_identifier": "rentable-identity-9233",
        "pets_allowed": true
      },
      "relationships": {
        "tags": {
          "data": [
            {
              "type": "tags",
              "id": "286"
            },
            {
              "type": "tags",
              "id": "296"
            }
          ]
        }
      }
    },
    {
      "type": "invoice_items",
      "id": "invoice_item_8812189",
      "attributes": {
        "name": {
          "nl": "Huur",
          "en": "Rent"
        },
        "quantity": 1,
        "quantity_type": "fixed",
        "price": 356,
        "type": "cost_down",
        "in_advertised_price": true,
        "product_name": "Rent - 2-pers superdeluxe",
        "sku": "rent_4726",
        "display_quantity_type": {
          "nl": "Per verblijf",
          "en": "Per accommodation"
        }
      }
    },
    {
      "type": "invoice_items",
      "id": "invoice_item_8812190",
      "attributes": {
        "name": {
          "nl": "Handdoeken",
          "en": "Towels"
        },
        "quantity": 1,
        "quantity_type": "fixed",
        "price": 6,
        "type": "cost_down",
        "in_advertised_price": false,
        "product_name": "Towels",
        "sku": "extra_cost_18851",
        "display_quantity_type": {
          "nl": "Per verblijf",
          "en": "Per accommodation"
        }
      }
    }
  ]
}

Creates an option.

Update an option

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/options/911610?include=tags,available_extras,invoice_items&token=f42604ea8bdd573fc279dfb8905ea9626ae3991a -d '
  {
    "data": {
      "type": "options",
      "id": "911610",
      "attributes": {
        "title": "mr",
        "first_name": "Ruud",
        "last_name": "Seydel",
        "date_of_birth": "1989-01-25",
        "email": "ruud@bookingexperts.nl",
        "phone": "0881168901",
        "address": "Het eeftink",
        "number": "11-12",
        "city": "Enschede",
        "postalcode": "7541WH",
        "country_code": "NL",
        "receive_newsletter": true,
        "is_company": true,
        "company": "Booking Experts B.V.",
        "vat_nr": "NL851863681B01",
        "has_custom_invoice_details": true,
        "debtor": {
          "name": "Ali Ilboga",
          "email": "billing@bookingexperts.nl",
          "address": "Het Eeftink 11-12",
          "postalcode": "7541WH",
          "city": "Enschede",
          "country_code": "NL"
        },
        "chosen_extras": [{
          "extra_id": "invoice_item_template_18719",
          "quantity": 5,
          "memo": "My child is 1.80m, will he fit?"
        }]
      }
    }
  }' -X PATCH \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Returns

{
  "data": {
    "type": "options",
    "id": "911610",
    "links": {},
    "attributes": {
      "status": "placed",
      "token": "f42604ea8bdd573fc279dfb8905ea9626ae3991a",
      "start_date": "2017-08-01",
      "checkin_time": "15:00",
      "checkout_time": "11:00",
      "end_date": "2017-08-08",
      "currency": "EUR",
      "guest_group": {
        "seniors": 0,
        "adults": 2,
        "adolescents": 0,
        "children": 0,
        "babies": 0,
        "pets": 0
      },
      "chosen_extras": [
        {
          "extra_id": "invoice_item_template_18719",
          "memo": "My child is 1.80m, will he fit?",
          "quantity": 5
        }
      ],
      "title": "mr",
      "first_name": "Ruud",
      "last_name": "Seydel",
      "date_of_birth": "1989-01-25",
      "email": "ruud@bookingexperts.nl",
      "phone": "0881168901",
      "address": "Het eeftink",
      "number": "11-12",
      "postalcode": "7541WH",
      "city": "Enschede",
      "country_code": "NL",
      "is_company": true,
      "company": "Booking Experts B.V.",
      "vat_nr": "NL851863681B01",
      "has_custom_invoice_details": true,
      "debtor": {
        "name": "Ali Ilboga",
        "email": "billing@bookingexperts.nl",
        "address": "Het Eeftink 11-12",
        "postalcode": "7541WH",
        "city": "Enschede",
        "country_code": "NL"
      },
      "receive_newsletter": true,
      "traffic_source_options": [
        {
          "id": 205668,
          "label": "Vakantiebeurs"
        }
      ],
      "traffic_source": null,
      "labels": ["left accommodation in unacceptable state"],
      "total": 7014.0,
      "deposit": 0.0,
      "rent": 7000.0,
      "provision": 700.0,
      "invoice_details": null,
      "after_payment_return_url": null,
      "payment_plan_options": [
        {
          "id": "total",
          "price": 7014.0
        }
      ],
      "payment_plan": "total",
      "questions_completed": false,
      "deposit_completed": false,
      "coupon_allowed": false,
      "coupon": null,
      "group_details_required": false
    },
    "relationships": {
      "category": {
        "data": {
          "type": "categories",
          "id": "5140"
        }
      },
      "invoice_items": {
        "data": [
          {
            "type": "invoice_items",
            "id": "invoice_item_8717406"
          },
          {
            "type": "invoice_items",
            "id": "invoice_item_8717407"
          }
        ]
      },
      "available_extras": {
        "data": [
          {
            "type": "extras",
            "id": "invoice_item_template_18719"
          },
          {
            "type": "extras",
            "id": "package_437"
          }
        ]
      },
      "tags": {
        "type": "tags",
        "id": "1476"
      }
    }
  },
  "included": [
    {
      "type": "tags",
      "id": "1476",
      "attributes": {
        "name": {
          "nl": "Gratis Wi-Fi",
          "en": "Free Wi-Fi"
        },
        "search": false,
        "highlight": false,
        "position": 0,
        "scheme_attribute": "wifi"
      },
      "relationships": {
        "groupings": {
          "data": {
            "type": "groupings",
            "id": "1023"
          }
        }
      }
    },
    {
      "type": "extras",
      "id": "invoice_item_template_18719",
      "attributes": {
        "name": {
          "nl": "Kinderbed",
          "en": "Child's bed"
        },
        "description": {
          "nl": "Korte omschrijving",
          "en": "Short description"
        },
        "quantity_required": false,
        "memo_required": false,
        "memo_description": null,
        "price": 14.0,
        "maximum_quantity": 2,
        "image_url": null
      }
    },
    {
      "type": "extras",
      "id": "package_437",
      "attributes": {
        "name": {
          "nl": "Sauna arrangement",
          "en": "Sauna package"
        },
        "description": {
          "nl": "Dit is een HTML opgemaakte tekst over <strong>Sauna</strong>",
          "en": "This is a text in HTML markup about <strong>Sauna</strong>"
        },
        "quantity_required": false,
        "memo_required": false,
        "memo_description": null,
        "price": 215.0,
        "maximum_quantity": 1,
        "image_url": null
      }
    },
    {
      "type": "invoice_items",
      "id": "invoice_item_8717406",
      "attributes": {
        "name": {
          "nl": "Huur",
          "en": "Rent"
        },
        "quantity": 1.0,
        "price": 7000.0,
        "type": "cost_down",
        "in_advertised_price": true,
        "product_name": "Rent - Luxury villa for 12 persons",
        "sku": "rent_5140",
        "quantity_type": "Per verblijf"
      }
    },
    {
      "type": "invoice_items",
      "id": "invoice_item_8717407",
      "attributes": {
        "name": {
          "nl": "Kinderbed",
          "en": "Child's bed"
        },
        "quantity": 5.0,
        "price": 14.0,
        "type": "cost_down",
        "in_advertised_price": true,
        "product_name": "Cot",
        "sku": "extra_cost_18719",
        "quantity_type": "Per verblijf"
      }
    }
  ]
}

Updates a option with customer information and/or supplements.

Delete an option

curl -X DELETE https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/options/911610?token=f42604ea8bdd573fc279dfb8905ea9626ae3991a \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

The server will respond with a 204 No Content HTTP status code.

Deletes the option and thus cancels it.

Organizations

An organization has one or many administrations.

The organization object

Attribute Meaning
name Translated name.

List all organizations

curl https://api.bookingexperts.nl/v1/organizations \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/organizations?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/organizations?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/organizations?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "organizations",
      "id": "133",
      "attributes": {
        "name": {
          "en": "Api"
        }
      }
    }
  ]
}

Returns a list of all organizations you have access to.

Package entries

A package entry is part of a package.

The package entry object

Attribute Meaning
name Translated name.
quantity The quantity of this entry that is available in the package.

Packages

Packages are combined extras. They are invoiced as one invoice line but can contain multiple extras. For example: a Sauna package which includes "Towels", "Sauna tickets" and "Bathrobes" which can be bought together in one package which is normally cheaper that buying all the same extras individually.

The package object

Attribute Meaning
name Translated name.
short_description Translated short description.
description Translated description formatted in plain text.
position Position used to display a sorted list.
rentable_type Rental segment of accommodations it can be used for. DEPRECATED: use the rentable_segment relationship instead to retrieve the rentable segment of the category, and then use RentableSegment#semantic_segment. For example: bungalow, camping, hotelroom, berth, apartment, accommodation.

List all packages

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/packages \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/parks/388/packages?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/parks/388/packages?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/parks/388/packages?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "packages",
      "id": "437",
      "attributes": {
        "name": {
          "nl": "Sauna arrangement",
          "en": "Sauna package"
        },
        "short_description": {
          "nl": "Geniet van een geweldige sauna",
          "en": "Enjoy an awesome sauna"
        },
        "description": {
          "nl": "Dit is een HTML opgemaakte tekst over <strong>Sauna</strong>",
          "en": "This is a HTML formatted description of <strong>Sauna</strong>"
        },
        "position": 0
      },
      "relationships": {
        "rentable_segment": {
          "data": {
            "type": "rentable_segments",
            "id": "1"
          }
        },
        "images": {
          "data": [
            {
              "type": "images",
              "id": "48248"
            }
          ]
        },
        "package_entries": {
          "data": [
            {
              "type": "package_entries",
              "id": "1007"
            },
            {
              "type": "package_entries",
              "id": "1006"
            }
          ]
        }
      }
    }
  ]
}

Returns a list of all packages

Search packages

The package search endpoint returns packages that are probably available in or near the provided period. It only checks restrictions on the stay period. Other restrictions may cause a package not to be available, but they may still be returned by this endpoint. For example:

Packages will be returned in order of relevance: the package that the user would probably be interested in will be listed first.

curl https://api.bookingexperts.nl/v1/package_availabilities/search?filter[overlaps_date]=2017-08-01&filter[semantic_segments]=bungalow&limit=4 \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/package_availabilities/search?filter%5Boverlaps_date%5D=2017-08-01&filter%5Bsemantic_segments%5D=bungalow&limit=4&page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/package_availabilities/search?filter%5Boverlaps_date%5D=2017-08-01&filter%5Bsemantic_segments%5D=bungalow&limit=4&page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/package_availabilities/search?filter%5Boverlaps_date%5D=2017-08-01&filter%5Bsemantic_segments%5D=bungalow&limit=4&page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "packages",
      "id": "1",
      "attributes": {
        "name": {
          "nl": "Arrangement 1",
          "en": "Package 1"
        },
        "short_description": {
          "nl": "Korte omschrijving van arrangement 1",
          "en": "Short description of package 1"
        },
        "description": {
          "nl": "Omschrijving van arrangement 1",
          "en": "Description of package 1"
        },
        "position": 1,
        "searchable": true,
        "fixed_period": true
      },
      "relationships": {
        "images": {
          "data": [
            {
              "type": "images",
              "id": "62851"
            }
          ]
        },
        "package_entries": {
          "data": [
            {
              "type": "package_entries",
              "id": "2502"
            },
            {
              "type": "package_entries",
              "id": "2501"
            }
          ]
        }
      }
    },
    {
      "type": "packages",
      "id": "2",
      "attributes": {
        "name": {
          "nl": "Arrangement 2",
          "en": "Package 2"
        },
        "short_description": {
          "nl": "Korte omschrijving arrangement 2",
          "en": "Short description of package 2"
        },
        "description": {
          "nl": "Omschrijving arrangement 2",
          "en": "Description of package 2"
        },
        "position": 2,
        "searchable": true,
        "fixed_period": false
      },
      "relationships": {
        "images": {
          "data": [
            {
              "type": "images",
              "id": "56466"
            }
          ]
        },
        "package_entries": {
          "data": [
            {
              "type": "package_entries",
              "id": "2377"
            }
          ]
        }
      }
    }
  ]
}

Filters

To filter on overlapping date

curl -g "https://api.bookingexperts.nl/v1/package_availabilities/search?filter[overlaps_date]=2017-07-01..2017-07-08" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

To filter on administration ids

curl -g "https://api.bookingexperts.nl/v1/package_availabilities/search?filter[overlaps_date]=2017-07-01..2017-07-08&filter[administration_ids]=1,2" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

To filter on semantic segments

curl -g "https://api.bookingexperts.nl/v1/package_availabilities/search?filter[overlaps_date]=2017-07-01..2017-07-08&[semantic_segments]=bungalow,apartment" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"
Filter Examples Meaning
overlaps_date 2017-07-01..2017-07-08 Required. Filter on package availabilities that overlap the supplied period.
rentable_types bungalow,apartment Filter on rental segments. DEPRECATED: filter by semantic_segments instead. Available types: bungalow, camping, hotelroom, berth, apartment, accommodation.
semantic_segments bungalow,apartment Filter on rental segments. Available types: bungalow, camping, hotelroom, berth, apartment, accommodation.
administration_ids 1,2 Filter on administrations.

Includes

You can include extra relations with this endpoint by adding an include parameter. Like this:

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/packages?include=image,package_entries,rentable_segment \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Available includes are:

Include Model
rentable_segment Rentable segment
images Image
package_entries Package entry

Package campaigns

Package campaigns are used to promote multiple packages at once. For example, this can be used to promote similar packages with different periods.

The package campaign object

Attribute Meaning
name Translated name.
description Translated description formatted in plain text.
position Position used to display a sorted list.
image_url Image of the package campaign

List all packages

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/package_campaigns \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "http://api.lvh.me:3000/v1/administrations/1/package_campaigns?page%5Bnumber%5D=1",
    "self": "http://api.lvh.me:3000/v1/administrations/1/package_campaigns?page%5Bnumber%5D=1",
    "last": "http://api.lvh.me:3000/v1/administrations/1/package_campaigns?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "id": "2",
      "type": "package_campaigns",
      "attributes": {
        "name": {
          "nl": "Sauna arrangementen"
        },
        "description": {
          "nl": "We bieden meerdere mooie sauna arrangementen aan, je kan er hier 1 kiezen!"
        },
        "position": 0,
        "image_url": {
          "original": "https://d366p4says9zep.cloudfront.net/uploads/package_campaign/image/2/sauna.jpg",
          "banner": "https://d366p4says9zep.cloudfront.net/uploads/package_campaign/image/2/banner_sauna.jpg",
          "large": "https://d366p4says9zep.cloudfront.net/uploads/package_campaign/image/2/large_sauna.jpg",
          "polaroid": "https://d366p4says9zep.cloudfront.net/uploads/package_campaign/image/2/polaroid_sauna.jpg",
          "thumb": "https://d366p4says9zep.cloudfront.net/uploads/package_campaign/image/2/thumb_sauna.jpg"
        }
      },
      "relationships": {
        "packages": {
          "data": [
            {
              "type": "packages",
              "id": "1"
            },
            {
              "type": "packages",
              "id": "3"
            }
          ]
        }
      }
    }
  ]
}

Returns a list of all packages

Includes

You can include extra relations with this endpoint by adding an include parameter. Like this:

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/packages?include=packages \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Available includes are:

Include Model
packages Package

Payment methods

Payment methods that are available for payment. The actual payments are handled by a third party payment service provider.

The payment method object

Attribute Meaning
image_url Contains a png and svg version of the logo of the payment method.

List administration payment methods

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/payment_methods \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/payment_methods?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/payment_methods?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/payment_methods?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "payment_methods",
      "id": "ideal",
      "attributes": {
        "image_url": {
          "svg": "https://api.bookingexperts.nl/assets/icons/payment_methods/ideal.svg",
          "png": "https://api.bookingexperts.nl/assets/icons/payment_methods/ideal.png"
        }
      }
    },
    {
      "type": "payment_methods",
      "id": "banktransfer",
      "attributes": {
        "image_url": {
          "svg": "https://api.bookingexperts.nl/assets/icons/payment_methods/banktransfer.svg",
          "png": "https://api.bookingexperts.nl/assets/icons/payment_methods/banktransfer.png"
        }
      }
    }
  ]
}

Returns a list of all payment methods for the given administration.

List organization payment methods

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/payment_methods \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/payment_methods?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/payment_methods?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/payment_methods?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "payment_methods",
      "id": "ideal",
      "attributes": {
        "image_url": {
          "svg": "https://api.bookingexperts.nl/assets/icons/payment_methods/ideal.svg",
          "png": "https://api.bookingexperts.nl/assets/icons/payment_methods/ideal.png"
        }
      }
    },
    {
      "type": "payment_methods",
      "id": "banktransfer",
      "attributes": {
        "image_url": {
          "svg": "https://api.bookingexperts.nl/assets/icons/payment_methods/banktransfer.svg",
          "png": "https://api.bookingexperts.nl/assets/icons/payment_methods/banktransfer.png"
        }
      }
    },
    {
      "type": "payment_methods",
      "id": "mastercard",
      "attributes": {
        "image_url": {
          "svg": "https://api.bookingexperts.nl/assets/icons/payment_methods/mastercard.svg",
          "png": "https://api.bookingexperts.nl/assets/icons/payment_methods/mastercard.png"
        }
      }
    }
  ]
}

Returns a list of all payment methods for all underlying administrations. It can happen that one payment method is supported in one administration but not in others. This is usually the case when an organization has administrations in different countries.

Regions

User defined region which can be used to describe a broad range of regions. For example "Southern of France", "Overijssel", "Northern Africa".

The region object

Attribute Meaning
name Translated name.
country_code ISO 3166-1 alpha-2 country code.

List all regions

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/regions \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/regions?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/regions?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/regions?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "regions",
      "id": "9",
      "attributes": {
        "name": {
          "nl": "Overijssel",
          "en": "Province of Overijssel"
        },
        "country_code": "NL"
      },
      "relationships": {
        "cities": {
          "data": [
            {
              "type": "cities",
              "id": "2"
            }
          ]
        }
      }
    }
  ]
}

Returns a list of all regions

Includes

Include Object
cities City

Rentables

An accommodation that can be rented as part of reservations and maps. A rentable is a period in which a physical accommodation can be rented. A physical accommodation can have multiple rentables, each representing different configurations (category, tags, pet policy, for rent, etc...) of the same physical accommodation.

The rentable object

Attribute Meaning
name The name of the rentable
map_identifier The identifier of the rentable within the map (if any). This is the same for every rentable of the same physical accommodation.
pets_allowed Whether or not pets are allowed for this rentable
date_range Dates on which this rentable can be rented

The following attributes are not included by default, but can be included using field sets:

Attribute Meaning
unbooked_dates A list of date ranges indicating all 'unbooked' (i.e., not booked nor blocked) dates for this rentable in the upcoming 2 years

Rentables retrieved using the map endpoint have these additional attributes:

Attribute Meaning
preference_costs Yields cumulative preference costs in the given currency (or the default currency) when this rentable is explicitly chosen

List all rentables

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/rentables \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/parks/388/rentables?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/parks/388/rentables?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/parks/388/rentables?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "rentables",
      "id": "1234",
      "attributes": {
        "name": "House 1",
        "map_identifier": "rentable-1234",
        "pets_allowed": true
      },
      "relationships": {
        "category": {
          "data": {
            "type": "categories",
            "id": "5140"
          }
        },
        "tags": {
          "data": [
            {
              "type": "tags",
              "id": "1578"
            },
            {
              "type": "tags",
              "id": "1579"
            }
          ]
        },
        "images": {
          "data": [
            {
              "type": "images",
              "id": "58245"
            },
            {
              "type": "images",
              "id": "58246"
            }
          ]
        }
      }
    }
  ]
}

To include unbooked dates

curl -g "https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/rentables?fields[rentables]=%2Bunbooked_dates" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/parks/388/rentables?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/parks/388/rentables?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/parks/388/rentables?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "rentables",
      "id": "1234",
      "attributes": {
        "name": "House 1",
        "map_identifier": "rentable-1234",
        "pets_allowed": true,
        "unbooked_dates": ["2018-09-06..2019-09-06", "2019-09-16..2020-09-06"]
      },
      "relationships": {
        "category": {
          "data": {
            "type": "categories",
            "id": "5140"
          }
        },
        "tags": {
          "data": [
            {
              "type": "tags",
              "id": "1578"
            },
            {
              "type": "tags",
              "id": "1579"
            }
          ]
        },
        "images": {
          "data": [
            {
              "type": "images",
              "id": "58245"
            },
            {
              "type": "images",
              "id": "58246"
            }
          ]
        }
      }
    }
  ]
}

Returns a list of all rentables.

Includes

You can include extra relations with this endpoint by adding an include parameter. Like this:

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/rentables?include=category,tags,images \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Available includes are:

Include Model
category Category
tags Tag
images Image

Rentable segments

The rental segment an accommodation belongs to.

The rentable segment object

Attribute Meaning
semantic_segment A semantic, global, rental segment identifier. Useful for comparing rental segments of different organizations.
name Translated name.

List all rentable segments

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/rentable_segments \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/rentable_segments?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/rentable_segments?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/rentable_segments?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "rentable_segments",
      "id": "100",
      "attributes": {
        "semantic_segment": "camping",
        "name": {
          "nl": "Campings",
          "en": "Campings"
        }
      }
    }
  ]
}

Returns a collection of all rentable segments.

Reservations

In the examples we use the term main guest which is used to describe the person that is making the reservation. Most organizations require detailed information about the main guest and not from every individual that is part of the guest group.

A reservation can be in the following states:

Status Meaning
Placed The reservation is blocking, but not yet confirmed. If the reservation is not confirmed within 24 hours it will be cancelled.
Finished The reservation is blocking and has been confirmed by the tour operator. Either the reservation is an option or the administration still needs to perform additional steps to confirm the reservation.
Confirmed The reservation is confirmed and blocking.
Cancelled The reservation has been cancelled.

The reservation object

Attribute Meaning
token Unique secret token.
start_date Date of arrival.
end_date Date of checkout.
late_checkout Late check-out enabled
checkin_time Time at from which the guest can checkin.
checkout_time Time at or before the guest should checkout.
confirmed_at Timestamp (iso8601, e.g.: "2018-03-27T07:32:51Z", meaning 07:32:51 UTC) of the moment on which this reservation has been confirmed.
currency Currency used for prices.
locale Locale that should be used when sending e-mails and invoices to the guest. Do not specify to default to the administration's native locale. If specified, should be compatible with the administration's available locales (see the administration endpoint).
status Status of the reservation. Can be placed, finished, confirmed, cancelled.
guest_group Description of the guests. Describes amount of seniors, adults, adolescents, children, babies, pets.
payment_deadlines Array of hashes with keys date, open_amount, paid_amount per payment deadline.
chosen_extras Array of hashes with keys extra_id, quantity, memo per chosen extra (optional). Available extras can be retrieved by using the available_extras include, or via the extras relation of the list of categories, or from the extras endpoint.
is_company If the reservation is reserved by a company.
company Company name.
vat_nr Company vat number.
booking_nr Booking number.
remote_booking_nr External booking number.
title Title of the main guest. Can be null or mr, ms, miss, family.
first_name First name of the main guest.
last_name Last name of the main guest.
date_of_birth Date of birth of the main guest.
email E-mail of the main guest.
phone Phone of the main guest.
address Address of the main guest.
number Address number of the main guest.
city City name of the main guest.
postalcode Postal code of the main guest.
country_code ISO 3166-1 alpha-2 country code.
available_parking_spots Number of available parking spots for the reservation (if known). Will only be shown if the administration uses the license plates module.
license_plates An array of license plate numbers. It should not exceed the number of available parking spots. Will only be shown if the administration uses the license plates module.
receive_newsletter If the main guest wants to receive a newsletter on by e-mail.
traffic_source_options Array of hashes with keys id, label (human readable label).
traffic_source Selected traffic source option. Contains the id from one of the traffic_source_options.
labels Array of strings with label names linked with the reservation or customer.
payment_plan_options Array of hashes with keys id, price, description (optional).
payment_plan Selected payment plan option. Contains the id from one of the payment_plan_options.
after_payment_return_url Callback url where the client is redirected after making / aborting the online payment, completing additional questions or supplying a deposit.
has_custom_invoice_details If the reservation has a different invoice information.
debtor Contains custom_invoice_details. Hash that contains name, email, address, postalcode, city, country_code
total Total what it will cost the guest whether or not some part of it is charged by the tour operator.
deposit Total deposit that is charged to the guest. Of course the guest receives this amount back after checkout. It's not included in the total.
rent Total rent amount which is included in the total.
provision Total calculated provision for the tour operator. It's not included in the total. This is the amount the administration will pay to the tour operator for this reservation.
invoice_details Remarks for the supplied invoice. For example: "Please note, on arrival you have to pay tourist tax".
has_rentable_map Yields true when choosing the rentable from map is supported for this reservation
questions_completed If (additional) questions after the reservation are completed.
deposit_completed If (additional) deposit is fulfilled.
guest_list_completed If the reservation's guest list has been completely filled in (when enabled).
fixed_rentable Whether or not reservation is made on a specific rentable, as opposed to a category.
note A remark by the guest.
late_checkout_possible Whether late check-out is possible for this reservation.
coupon_codes Applied coupon codes. Coupon codes are code that trigger a specific discount action.
pending_vouchers Vouchers to be applied when reservation is confirmed. Vouchers are unique, the balance can be spend only once. The balance attribute is the balance that will be left after the voucher is applied upon confirming the reservation.

Creating or requesting reservations also returns the payment link for the reservation. A redirect to the pay url is always required to be able to complete a reservation.

Link Meaning
pay Send / redirect a customer to this url to allow the customer to make an online payment.

After payment return url callback

If after_payment_return_url is given for a reservation, the customer will be redirected to that url together with a bunch of query params: reservation_id, token and status. status can have the following values:

Status Meaning
success Payment is successfull.
open The result of the payment is still undetermined. A final state is expected soon.
open_but_confirmed The result of the payment is still undetermined, but this is to be expected. For example, a bank transfer will take a while. The reservation has been confirmed for now but might be cancelled again should a payment not be made in a timely manner.
failure Payment has failed.
failure_final Payment has failed. We know for certain this is the final state and it won't change any further.
cancelled Payment has been cancelled by the customer.
deposit_completed Deposit has been made by the customer. This can only happen if the administration requests deposits from customers, and the customer is sent to the deposit page, either by you sending them to the appropriate link, or by using the link in an email that might be sent to the customer.
questions_completed Additioinal questions have been answered by the customer. This can only happen if the administration asks additional questions to customers, and the customer is sent to the questions page, either by you sending them to the appropriate link, or by using the link in an email that might be sent to the customer.

Reservation includes

You can include extra relations to the endpoints by adding an include parameter. Like this:

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/reservations/911610?include=category.terms&token=f42604ea8bdd573fc279dfb8905ea9626ae3991a \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Available includes are:

Include Model
available_discount_cards DiscountCard
available_primary_packages Package
available_extras Extra
category Category
invoice_items InvoiceItem
invoice_items.chosen_extra Extra
invoice_items.costs Cost
discount_card DiscountCard
primary_package Package
rentable Rentable
tags Tag

Retrieve a reservation

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/reservations/911610?include=tags,available_extras,invoice_items&token=f42604ea8bdd573fc279dfb8905ea9626ae3991a \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Returns

available_parking_spotsjson { "data": { "type": "reservations", "id": "911610", "links": { "pay": "https://api.bookingexperts.nl/nl/front/parks/388:Holiday-resort/reservations/911610/payment_requests/new?token=f42604ea8bdd573fc279dfb8905ea9626ae3991a" }, "attributes": { "status": "confirmed", "token": "f42604ea8bdd573fc279dfb8905ea9626ae3991a", "start_date": "2017-08-01", "checkin_time": "15:00", "checkout_time": "11:00", "end_date": "2017-08-08", "booking_nr": "12345678", "remote_booking_nr": "12345678", "currency": "EUR", "fixed_rentable": false, "guest_group": { "seniors": 0, "adults": 2, "adolescents": 0, "children": 0, "babies": 0, "pets": 0 }, "payment_deadlines": [ { "date": "2019-02-20", "open_amount": 0.0, "paid_amount": 500.0 }, { "date": "2019-03-20", "open_amount": 500.0, "paid_amount": 0.0 } ], "chosen_extras": [ { "extra_id": "invoice_item_template_18719", "memo": "My child is 1.80m, will he fit?", "quantity": 5 } ], "title": "mr", "first_name": "Ruud", "last_name": "Seydel", "date_of_birth": "1989-01-25", "email": "ruud@bookingexperts.nl", "phone": "0881168901", "address": "Het eeftink", "number": "11-12", "postalcode": "7541WH", "city": "Enschede", "country_code": "NL", "is_company": true, "company": "Booking Experts B.V.", "vat_nr": "NL851863681B01", "has_custom_invoice_details": true, "debtor": { "name": "Ali Ilboga", "email": "billing@bookingexperts.nl", "address": "Het Eeftink 11-12", "postalcode": "7541WH", "city": "Enschede", "country_code": "NL" }, "available_parking_spots": 2, "license_plates": [ "19-XNZ-1", "19-XNZ-2" ], "receive_newsletter": true, "traffic_source_options": [ { "id": "205668", "label": "Vakantiebeurs" } ], "traffic_source": null, "labels": ["local", "vandal"], "total": 7014.0, "deposit": 0.0, "rent": 7000.0, "provision": 700.0, "invoice_details": null, "after_payment_return_url": null, "payment_plan_options": [ { "id": "total", "price": 7014.0 } ], "payment_plan": "total", "questions_completed": false, "deposit_completed": false, "group_details_required": false, "coupon_codes": [], "pending_vouchers": [] }, "relationships": { "category": { "data": { "type": "categories", "id": "5140" } }, "invoice_items": { "data": [ { "type": "invoice_items", "id": "invoice_item_8717406" }, { "type": "invoice_items", "id": "invoice_item_8717407" } ] }, "available_extras": { "data": [ { "type": "extras", "id": "invoice_item_template_18719" }, { "type": "extras", "id": "package_437" } ] }, "tags": { "type": "tags", "id": "1476" } } }, "included": [ { "type": "tags", "id": "1476", "attributes": { "name": { "nl": "Gratis Wi-Fi", "en": "Free Wi-Fi" }, "search": false, "highlight": false, "position": 0, "scheme_attribute": "wifi" }, "relationships": { "groupings": { "data": { "type": "groupings", "id": "1023" } } } }, { "type": "extras", "id": "invoice_item_template_18719", "attributes": { "name": { "nl": "Kinderbed", "en": "Child's bed" }, "description": { "nl": "Korte omschrijving", "en": "Short description" }, "quantity_required": false, "memo_required": false, "memo_description": null, "price": 14.0, "maximum_quantity": 2, "image_url": null } }, { "type": "extras", "id": "package_437", "attributes": { "name": { "nl": "Sauna arrangement", "en": "Sauna package" }, "description": { "nl": "Dit is een HTML opgemaakte tekst over <strong>Sauna</strong>", "en": "This is a text in HTML markup about <strong>Sauna</strong>" }, "quantity_required": false, "memo_required": false, "memo_description": null, "price": 215.0, "maximum_quantity": 1, "image_url": null } }, { "type": "invoice_items", "id": "invoice_item_8717406", "attributes": { "name": { "nl": "Huur", "en": "Rent" }, "quantity": 1.0, "price": 7000.0, "type": "cost_down", "in_advertised_price": true, "product_name": "Rent - Luxury villa for 12 persons", "sku": "rent_5140", "quantity_type": "Per verblijf", "invoiced_to": "customer" } }, { "type": "invoice_items", "id": "invoice_item_8717407", "attributes": { "name": { "nl": "Kinderbed", "en": "Child's bed" }, "quantity": 5.0, "price": 14.0, "type": "cost_down", "in_advertised_price": true, "product_name": "Cot", "sku": "extra_cost_18719", "quantity_type": "Per verblijf", "invoiced_to": "customer" }, "relationships": { "chosen_extra": { "data": { "type": "extras", "id": "invoice_item_template_18719" } } } } ] } ``

Returns the details of a reservation

Retrieve all reservations (Experimental)

This experimental endpoint returns all confirmed reservations made on an administration. This feature is restricted and has to be enabled by an administration for your account.

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/reservations?include=tags,invoice_items \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

This call returns an array with the same data structure as the Retrieve a reservation call.

Filters

To filter on start_date

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/reservations?start_date=2018-01-01..2018-12-31 \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"
Filter Examples Meaning
start_date 2017-07-01, 2017-07-01..2017-07-02 Filter on start_date.
end_date 2017-07-01, 2017-07-01..2017-07-02 Filter on end_date.
confirmed_at 2013-12-01T13:00:00Z..2013-12-01T14:00:00Z Filter on reservations that have been confirmed within this time range. Useful for incrementally fetching reservations.
booking_nr 12345678 Filter on booking nr.

Preview a reservation

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/reservations/preview?include=invoice_items -d '
  {
    "data": {
      "type": "reservations",
      "attributes": {
        "start_date": "2017-08-01",
        "end_date": "2017-08-08",
        "guest_group": {
          "adults": 2
        },
        "currency": "EUR"
      },
      "relationships": {
        "category": {
          "data": {
            "type": "categories",
            "id": "5140"
          }
        },
        "tags": {
          "data": [{
            "type": "tags",
            "id": 1476
          }]
        }
      }
    }
  }' -X POST \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Returns

{
  "data": {
    "type": "reservations",
    "id": null,
    "attributes": {
      "start_date": "2017-08-01",
      "checkin_time": "15:00",
      "checkout_time": "11:00",
      "end_date": "2017-08-08",
      "currency": "EUR",
      "guest_group": {
        "seniors": 0,
        "adults": 2,
        "adolescents": 0,
        "children": 0,
        "babies": 0,
        "pets": 0
      }
    },
    "relationships": {
      "category": {
        "data": {
          "type": "categories",
          "id": "5140"
        }
      },
      "invoice_items": {
        "data": [
          {
            "type": "invoice_items",
            "id": "a7edd2772560f17fb5e0"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "invoice_items",
      "id": "a7edd2772560f17fb5e0",
      "attributes": {
        "name": {
          "nl": "Huur",
          "en": "Rent"
        },
        "quantity": 1.0,
        "price": 7000.0,
        "type": "cost_down",
        "in_advertised_price": true,
        "product_name": "Rent - Luxury villa for 12 persons",
        "sku": "rent_5140",
        "quantity_type": "Per verblijf",
        "invoiced_to": "customer"
      }
    }
  ]
}

Query Parameters

Parameter Default Description
redeemable_codes[] null Array attribute to pass redeemable codes like a coupon code or voucher code. Booking Experts will figure out if it's a valid code and applies it. See coupon_codes and pending_vouchers in the reservation attributes.

Returns a preview which includes prices and included extra's. This can be used to give the guest an idea of how the total price is composed. You can you the same attributes as for creating a reservation.

Validate a reservation

curl "https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/reservations/validate" -d '
  {
    "data": {
      "type": "reservations",
      "attributes": {
        "start_date": "2017-08-01",
        "end_date": "2017-08-08",
        "guest_group": {
          "adults": 2
        },
        "currency": "EUR"
      },
      "relationships": {
        "category": {
          "data": {
            "type": "categories",
            "id": "5140"
          }
        },
        "tags": {
          "data": [{
            "type": "tags",
            "id": 1476
          }]
        }
      }
    }
  }' -X POST \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Returns

{
  "errors": [
    {
      "status": 422,
      "title": "Save resource failed",
      "detail": "can't be blank",
      "source": "attributes/first_name"
    },
    {
      "status": 422,
      "title": "Save resource failed",
      "detail": "can't be blank",
      "source": "attributes/postalcode"
    },
    {
      "status": 422,
      "title": "Save resource failed",
      "detail": "can't be blank",
      "source": "attributes/email"
    },
    {
      "status": 422,
      "title": "Save resource failed",
      "detail": "can't be blank",
      "source": "attributes/phone"
    },
    {
      "status": 422,
      "title": "Save resource failed",
      "detail": "can't be blank",
      "source": "attributes/date_of_birth"
    }
  ]
}

Similar to the preview action, but will return a list of errors when the passed in reservation is not valid. Otherwise, it will return a preview which includes prices and included extra's.

Create a reservation

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/reservations?include=rentable,invoice_items -d '
  {
    "data": {
      "type": "reservations",
      "attributes": {
        "start_date": "2017-10-06",
        "end_date": "2017-10-13",
        "guest_group": {
          "adults": 2
        },
        "currency": "EUR",
        "title": "mr",
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1983-11-05",
        "email": "info@bookingexperts.nl",
        "phone": "0647778135",
        "address": "Het eeftink",
        "number": "11-12",
        "city": "Enschede",
        "postalcode": "7541WH",
        "country_code": "NL",
        "available_parking_spots": 2,
        "license_plates": [
          "19-XNZ-1",
          "19-XNZ-2"
        ],
        "receive_newsletter": true,
        "is_company": true,
        "company": "Booking Experts B.V.",
        "vat_nr": "NL851863681B01",
        "booking_nr": "12345678",
        "remote_booking_nr": "12345678",
        "has_custom_invoice_details": true,
        "debtor": {
          "name": "Ali Ilboga",
          "email": "billing@bookingexperts.nl",
          "address": "Het Eeftink 11-12",
          "postalcode": "7541WH",
          "city": "Enschede",
          "country_code": "NL"
        }
      },
      "relationships": {
        "rentable": {
          "data": {
            "type": "rentables",
            "id": "35269"
          }
        },
        "category": {
          "data": {
            "type": "categories",
            "id": "4726"
          }
        },
        "tags": {
          "data": [{"id": "286", "type": "tags"}, {"id": "296", "type": "tags"}]
        }
      }
    }
  }' -X POST \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Returns

{
  "data": {
    "type": "reservations",
    "id": "926494",
    "links": {
      "pay": "https://api.bookingexperts.nl/nl/front/parks/388:Holiday-resort/reservations/926494/payment_requests/new?token=74cda7711a1fd6f4fcf950d4e0ea0b26513f8813"
    },
    "attributes": {
      "status": "placed",
      "token": "74cda7711a1fd6f4fcf950d4e0ea0b26513f8813",
      "start_date": "2017-10-06",
      "checkin_time": "15:00",
      "checkout_time": "11:00",
      "end_date": "2017-10-13",
      "currency": "EUR",
      "guest_group": {
        "seniors": 0,
        "adults": 2,
        "adolescents": 0,
        "children": 0,
        "babies": 0,
        "pets": 0
      },
      "title": "mr",
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1983-11-05",
      "email": "info@bookingexperts.nl",
      "phone": "0647778135",
      "address": "Het eeftink",
      "number": "11-12",
      "postalcode": "7541WH",
      "city": "Enschede",
      "country_code": "NL",
      "is_company": true,
      "company": "Booking Experts B.V.",
      "vat_nr": "NL851863681B01",
      "booking_nr": "12345678",
      "remote_booking_nr": "12345678",
      "has_custom_invoice_details": true,
      "debtor": {
        "name": "Ali Ilboga",
        "email": "billing@bookingexperts.nl",
        "address": "Het Eeftink 11-12",
        "postalcode": "7541WH",
        "city": "Enschede",
        "country_code": "NL"
      },
      "available_parking_spots": 2,
      "license_plates": [
        "19-XNZ-1",
        "19-XNZ-2"
      ],
      "receive_newsletter": true,
      "traffic_source_options": [],
      "traffic_source": null,
      "labels": [],
      "total": 362.0,
      "deposit": 0.0,
      "rent": 356.0,
      "provision": 0.0,
      "invoice_details": null,
      "has_rentable_map": true,
      "after_payment_return_url": null,
      "payment_plan_options": [
        {
          "id": "total",
          "price": 0
        }
      ],
      "payment_plan": "total",
      "questions_completed": false,
      "deposit_completed": false,
      "group_details_required": false,
      "coupon_codes": [],
      "pending_vouchers": []
    },
    "relationships": {
      "category": {
        "data": {
          "type": "categories",
          "id": "4726"
        }
      },
      "rentable": {
        "data": {
          "type": "rentables",
          "id": "35269"
        }
      },
      "tags": {
        "data": [
          {
            "type": "tags",
            "id": "286"
          },
          {
            "type": "tags",
            "id": "296"
          }
        ]
      },
      "invoice_items": {
        "data": [
          {
            "type": "invoice_items",
            "id": "invoice_item_8812189"
          },
          {
            "type": "invoice_items",
            "id": "invoice_item_8812190"
          }
        ]
      },
      "available_extras": {
        "data": [
          {
            "type": "extras",
            "id": "invoice_item_template_18118"
          },
          {
            "type": "extras",
            "id": "invoice_item_template_18849"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "rentables",
      "id": "35269",
      "attributes": {
        "name": "2psd-2",
        "map_identifier": "rentable-9233",
        "pets_allowed": true
      },
      "relationships": {
        "tags": {
          "data": [
            {
              "type": "tags",
              "id": "286"
            },
            {
              "type": "tags",
              "id": "296"
            }
          ]
        }
      }
    },
    {
      "type": "invoice_items",
      "id": "invoice_item_8812189",
      "attributes": {
        "name": {
          "nl": "Huur",
          "en": "Rent"
        },
        "quantity": 1,
        "quantity_type": "fixed",
        "price": 356,
        "type": "cost_down",
        "in_advertised_price": true,
        "product_name": "Rent - 2-pers superdeluxe",
        "sku": "rent_4726",
        "display_quantity_type": {
          "nl": "Per verblijf",
          "en": "Per accommodation"
        },
        "invoiced_to": "customer"
      }
    },
    {
      "type": "invoice_items",
      "id": "invoice_item_8812190",
      "attributes": {
        "name": {
          "nl": "Handdoeken",
          "en": "Towels"
        },
        "quantity": 1,
        "quantity_type": "fixed",
        "price": 6,
        "type": "cost_down",
        "in_advertised_price": false,
        "product_name": "Towels",
        "sku": "extra_cost_18851",
        "display_quantity_type": {
          "nl": "Per verblijf",
          "en": "Per accommodation"
        },
        "invoiced_to": "customer"
      }
    }
  ]
}

Creates a reservation.

Query Parameters

Parameter Default Description
confirm false If set to true, makes the reservation confirmed. A confirmed reservation will not expire. Unconfirmed reservations will expire after 24 hours.
redeemable_codes[] null Array attribute to pass redeemable codes like a coupon code or voucher code. Booking Experts will figure out if it's a valid code and applies it. See coupon_codes and pending_vouchers in the reservation attributes.

Update a reservation

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/reservations/911610?include=tags,available_extras,invoice_items&token=f42604ea8bdd573fc279dfb8905ea9626ae3991a -d '
  {
    "data": {
      "type": "reservations",
      "id": "911610",
      "attributes": {
        "title": "mr",
        "first_name": "Ruud",
        "last_name": "Seydel",
        "date_of_birth": "1989-01-25",
        "email": "ruud@bookingexperts.nl",
        "phone": "0881168901",
        "address": "Het eeftink",
        "number": "11-12",
        "city": "Enschede",
        "postalcode": "7541WH",
        "country_code": "NL",
        "available_parking_spots": 2,
        "license_plates": [
          "19-XNZ-1",
          "19-XNZ-2"
        ],
        "receive_newsletter": true,
        "is_company": true,
        "company": "Booking Experts B.V.",
        "vat_nr": "NL851863681B01",
        "booking_nr": "12345678",
        "remote_booking_nr": "12345678",
        "has_custom_invoice_details": true,
        "debtor": {
          "name": "Ali Ilboga",
          "email": "billing@bookingexperts.nl",
          "address": "Het Eeftink 11-12",
          "postalcode": "7541WH",
          "city": "Enschede",
          "country_code": "NL"
        },
        "chosen_extras": [{
          "extra_id": "invoice_item_template_18719",
          "quantity": 5,
          "memo": "My child is 1.80m, will he fit?"
        }]
      }
    }
  }' -X PATCH \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY"

Returns

{
  "data": {
    "type": "reservations",
    "id": "911610",
    "links": {
      "pay": "https://api.bookingexperts.nl/nl/front/parks/388:Holiday-resort/reservations/911610/payment_requests/new?token=f42604ea8bdd573fc279dfb8905ea9626ae3991a"
    },
    "attributes": {
      "status": "placed",
      "token": "f42604ea8bdd573fc279dfb8905ea9626ae3991a",
      "start_date": "2017-08-01",
      "checkin_time": "15:00",
      "checkout_time": "11:00",
      "end_date": "2017-08-08",
      "booking_nr": "12345678",
      "remote_booking_nr": "12345678",
      "currency": "EUR",
      "guest_group": {
        "seniors": 0,
        "adults": 2,
        "adolescents": 0,
        "children": 0,
        "babies": 0,
        "pets": 0
      },
      "chosen_extras": [
        {
          "extra_id": "invoice_item_template_18719",
          "memo": "My child is 1.80m, will he fit?",
          "quantity": 5
        }
      ],
      "title": "mr",
      "first_name": "Ruud",
      "last_name": "Seydel",
      "date_of_birth": "1989-01-25",
      "email": "ruud@bookingexperts.nl",
      "phone": "0881168901",
      "address": "Het eeftink",
      "number": "11-12",
      "postalcode": "7541WH",
      "city": "Enschede",
      "country_code": "NL",
      "is_company": true,
      "company": "Booking Experts B.V.",
      "vat_nr": "NL851863681B01",
      "has_custom_invoice_details": true,
      "debtor": {
        "name": "Ali Ilboga",
        "email": "billing@bookingexperts.nl",
        "address": "Het Eeftink 11-12",
        "postalcode": "7541WH",
        "city": "Enschede",
        "country_code": "NL"
      },
      "available_parking_spots": 2,
      "license_plates": [
        "19-XNZ-1",
        "19-XNZ-2"
      ],
      "receive_newsletter": true,
      "traffic_source_options": [
        {
          "id": "205668",
          "label": "Vakantiebeurs"
        }
      ],
      "traffic_source": null,
      "labels": ["left accommodation in unacceptable state"],
      "total": 7014.0,
      "deposit": 0.0,
      "rent": 7000.0,
      "provision": 700.0,
      "invoice_details": null,
      "after_payment_return_url": null,
      "payment_plan_options": [
        {
          "id": "total",
          "price": 7014.0
        }
      ],
      "payment_plan": "total",
      "questions_completed": false,
      "deposit_completed": false,
      "group_details_required": false,
      "coupon_codes": [],
      "pending_vouchers": []
    },
    "relationships": {
      "category": {
        "data": {
          "type": "categories",
          "id": "5140"
        }
      },
      "invoice_items": {
        "data": [
          {
            "type": "invoice_items",
            "id": "invoice_item_8717406"
          },
          {
            "type": "invoice_items",
            "id": "invoice_item_8717407"
          }
        ]
      },
      "available_extras": {
        "data": [
          {
            "type": "extras",
            "id": "invoice_item_template_18719"
          },
          {
            "type": "extras",
            "id": "package_437"
          }
        ]
      },
      "tags": {
        "type": "tags",
        "id": "1476"
      }
    }
  },
  "included": [
    {
      "type": "tags",
      "id": "1476",
      "attributes": {
        "name": {
          "nl": "Gratis Wi-Fi",
          "en": "Free Wi-Fi"
        },
        "search": false,
        "highlight": false,
        "position": 0,
        "scheme_attribute": "wifi"
      },
      "relationships": {
        "groupings": {
          "data": {
            "type": "groupings",
            "id": "1023"
          }
        }
      }
    },
    {
      "type": "extras",
      "id": "invoice_item_template_18719",
      "attributes": {
        "name": {
          "nl": "Kinderbed",
          "en": "Child's bed"
        },
        "description": {
          "nl": "Korte omschrijving",
          "en": "Short description"
        },
        "quantity_required": false,
        "memo_required": false,
        "memo_description": null,
        "price": 14.0,
        "maximum_quantity": 2,
        "image_url": null
      }
    },
    {
      "type": "extras",
      "id": "package_437",
      "attributes": {
        "name": {
          "nl": "Sauna arrangement",
          "en": "Sauna package"
        },
        "description": {
          "nl": "Dit is een HTML opgemaakte tekst over <strong>Sauna</strong>",
          "en": "This is a text in HTML markup about <strong>Sauna</strong>"
        },
        "quantity_required": false,
        "memo_required": false,
        "memo_description": null,
        "price": 215.0,
        "maximum_quantity": 1,
        "image_url": null
      }
    },
    {
      "type": "invoice_items",
      "id": "invoice_item_8717406",
      "attributes": {
        "name": {
          "nl": "Huur",
          "en": "Rent"
        },
        "quantity": 1.0,
        "price": 7000.0,
        "type": "cost_down",
        "in_advertised_price": true,
        "product_name": "Rent - Luxury villa for 12 persons",
        "sku": "rent_5140",
        "quantity_type": "Per verblijf",
        "invoiced_to": "customer"
      }
    },
    {
      "type": "invoice_items",
      "id": "invoice_item_8717407",
      "attributes": {
        "name": {
          "nl": "Kinderbed",
          "en": "Child's bed"
        },
        "quantity": 5.0,
        "price": 14.0,
        "type": "cost_down",
        "in_advertised_price": true,
        "product_name": "Cost",
        "sku": "extra_cost_18719",
        "quantity_type": "Per verblijf",
        "invoiced_to": "customer"
      },
      "relationships": {
        "chosen_extra": {
          "data": {
            "type": "extras",
            "id": "invoice_item_template_18719"
          }
        }
      }
    }
  ]
}

Updates a reservation with customer information and/or supplements.

Query Parameters

Parameter Default Description
confirm false If set to true, makes the reservation confirmed. A confirmed reservation will not expire. Unconfirmed reservations will expire after 24 hours.

Delete a reservation

curl -X DELETE https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/reservations/911610?token=f42604ea8bdd573fc279dfb8905ea9626ae3991a \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

The server will respond with a 204 No Content HTTP status code.

Cancels the reservation. Unconfirmed reservations are deleted after cancellation.

Query Parameters

Parameter Default Description
reason "Cancellation requested by %{channel.name}" Provide reason for cancelling the reservation

Review answers types

A review answer as part of reviews.

the review answer object

Attribute Meaning
question Translated question of the question that has been asked.
question_type Type of question asked, one of: rating (1-10), string (short text), text (long text) or boolean (yes/no).
answer_type Optional and only applicable to string or text answers. Possible values are: site_name, site_feedback, positive_feedback and negative_feedback. Only site_name and site_feedback answers should be publicly exposed.
position Position of the answer in the review.
answer The answer to the question. Its value depends on question_type.

Reviews

When a guest checks out they will receive a review form. A review form has at least one question. A question can be answered with a rating (1-10), a yes/no answer (boolean), a short text (string) or a long text (text).

The review object

Attribute Meaning
score Average score between 1 to 10
created_at Date time when review was submitted
locale Locale of the review
name Guest name
text Free form text comment from the guest
stayed_nights Amount of nights the guest stayed
stayed_date The day the guest checked-out

List all reviews

curl https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/reviews?include=review_answers \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "http://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/reviews?include=review_answers&page%5Bnumber%5D=1",
    "self": "http://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/reviews?include=review_answers&page%5Bnumber%5D=1",
    "last": "http://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/reviews?include=review_answers&page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "reviews",
      "id": "81832",
      "attributes": {
        "score": 8.0,
        "created_at": "2017-09-25 12:19:44 +0200",
        "locale": "en",
        "name": "John Doe",
        "text": "I had a great time!",
        "stayed_nights": 4,
        "stayed_date": "2017-09-22"
      },
      "relationships": {
        "category": {
          "data": {
            "type": "categories",
            "id": "4190"
          }
        },
        "review_answers": {
          "data": [
            {
              "type": "review_answers",
              "id": "736464"
            },
            {
              "type": "review_answers",
              "id": "736465"
            },
            {
              "type": "review_answers",
              "id": "736466"
            },
            {
              "type": "review_answers",
              "id": "736467"
            },
            {
              "type": "review_answers",
              "id": "736468"
            },
            {
              "type": "review_answers",
              "id": "736469"
            },
            {
              "type": "review_answers",
              "id": "736470"
            }
          ]
        },
      }
    }
  ],
  "included": [
    {
      "type": "review_answers",
      "id": "736464",
      "attributes": {
        "question": {
          "nl": "Ontvangst",
          "en": "Check in"
        },
        "question_type": "rating",
        "answer_type": null,
        "position": 1,
        "answer": 8
      }
    },
    {
      "type": "review_answers",
      "id": "736465",
      "attributes": {
        "question": {
          "nl": "Schoonmaak",
          "en": "Cleaning"
        },
        "question_type": "rating",
        "answer_type": null,
        "position": 2,
        "answer": 8
      }
    },
    {
      "type": "review_answers",
      "id": "736466",
      "attributes": {
        "question": {
          "nl": "Personeel",
          "en": "Staff"
        },
        "question_type": "rating",
        "answer_type": null,
        "position": 3,
        "answer": 8
      }
    },
    {
      "type": "review_answers",
      "id": "736467",
      "attributes": {
        "question": {
          "nl": "Faciliteiten",
          "en": "Facilities"
        },
        "question_type": "rating",
        "answer_type": null,
        "position": 4,
        "answer": 8
      }
    },
    {
      "type": "review_answers",
      "id": "736468",
      "attributes": {
        "question": {
          "nl": "Ligging",
          "en": "Location"
        },
        "question_type": "rating",
        "answer_type": null,
        "position": 5,
        "answer": 8
      }
    },
    {
      "type": "review_answers",
      "id": "736469",
      "attributes": {
        "question": {
          "nl": "Kindvriendelijk",
          "en": "Child friendly"
        },
        "question_type": "rating",
        "answer_type": null,
        "position": 6,
        "answer": 8
      }
    },
    {
      "type": "review_answers",
      "id": "736470",
      "attributes": {
        "question": {
          "nl": "Wat vond u leuk aan het verblijf?",
          "en": "What did you like?"
        },
        "question_type": "text",
        "answer_type": "site_feedback",
        "position": 7,
        "answer": "I had a great time!"
      }
    }
  ]
}

Returns a list of all reviews over all categories

Includes

Include Object
category Category
group_type GroupType
review_answers ReviewAnswer

Room types

Represents a room such as "bedroom" or "bathroom".

the room type object

Attribute Meaning
name Translated name.

List all room types

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/room_types \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/room_types?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/room_types?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/room_types?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "room_types",
      "id": "92",
      "attributes": {
        "name": {
          "nl": "Slaapkamer",
          "en": "Bedroom"
        }
      }
    }
  ]
}

Returns a list of all room types

Rooms

Rooms are part of a category.

The room object

Attribute Meaning
name Translated name.
position Position used to display a sorted list.

Semantic tag types

Semantic tag types are a predefined list of tag types which can be chosen by a user when creating a tag or custom attribute. The list will mostly be subject to minor changes for consistency. Semantic tag types are used in Custom Attributes and Tags.

The semantic tag type object

Attribute Meaning
semantic_name The computer readable name of the semantic tag type
description The description of the semantic tag type

List all semantic tag types

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/semantic_tag_types \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
   "data":[
      {
         "type":"semantic_tag_type",
         "attributes":{
            "semantic_name":"airco",
            "description":{
               "en":"Air conditioning",
               "nl":"Airconditioning"
            }
         }
      },
      {
         "type":"semantic_tag_type",
         "attributes":{
            "semantic_name":"minibar",
            "description":{
               "en":"Minibar",
               "nl":"Minibar"
            }
         }
      }
   ]
}

Returns a list of all semantic tag types

Tags

Tags are used to label categories, rooms and administrations. For example:

The tag object

Attribute Meaning
name Translated name.
position Position used to display a sorted list.
semantic_tag_type A computer readable type for the tag See. Semantic tag types for more information.

List all tags

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/tags \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/tags?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/tags?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/tags?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "tags",
      "id": "1477",
      "attributes": {
        "name": {
          "nl": "Sauna",
          "en": "Sauna"
        },
        "position": 0
      },
      "relationships": {
        "grouping": {
          "data": {
            "type": "groupings",
            "id": "1021"
          }
        }
      }
    },
    {
      "type": "tags",
      "id": "1476",
      "attributes": {
        "name": {
          "nl": "Gratis Wi-Fi",
          "en": "Free Wi-Fi"
        },
        "position": 1
      },
      "relationships": {
        "grouping": {
          "data": {
            "type": "groupings",
            "id": "1023"
          }
        }
      }
    }
  ]
}

Returns a list of all tags

Includes

You can include extra relations with this endpoint by adding an include parameter. Like this:

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/tags?include=grouping \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Available includes are:

Include Model
grouping Groupings

Terms

General terms and conditions

The terms object

Attribute Meaning
name Untranslated name.
content Translated content formatted in HTML.

List all terms

curl https://api.bookingexperts.nl/v1/organizations/$ORG_ID/terms \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Token $API_KEY" \
  -H "Accept-Language: nl,en"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/organizations/$ORG_ID/terms?page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/organizations/$ORG_ID/terms?page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/organizations/$ORG_ID/terms?page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "terms",
      "id": "166",
      "attributes": {
        "name": {
          "nl": "default",
          "en": "default"
        },
        "content": {
          "nl": "Waiting in the sky<br><br>",
          "en": null
        }
      },
      "relationships": {
        "categories": {
          "data": [
            {
              "type": "categories",
              "id": "4190"
            }
          ]
        },
        "administrations": {
          "data": [
            {
              "type": "administrations",
              "id": "386"
            },
            {
              "type": "administrations",
              "id": "388"
            }
          ]
        }
      }
    }
  ]
}

Returns a list of all terms available for an organization.

Users

Represents a user of the organization.

The user object

Attribute Meaning
on_call_locales List of locales for which the user is on call.
on_call_phone Phone number per locale.
on_call_email E-mail per locale.
name Name of the user.
avatar_url Avatar that represents the user.

List on call users for organizations

curl -g "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/users/on_call?filter[on_call_locale]=en"
  -H "Accept: application/vnd.api+json"
  -H "Accept-Language: nl,en"
  -H "Authorization: Token $API_KEY"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/users/on_call?filter%5Bhelp_locale%5D=en&page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/users/on_call?filter%5Bhelp_locale%5D=en&page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/organizations/$ORG_ID/users/on_call?filter%5Bhelp_locale%5D=en&page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "users",
      "id": "1670",
      "attributes": {
        "on_call_locales": [
          "en",
          "nl"
        ],
        "on_call_phone": {
          "nl": "0881168901",
          "en": "0881168901"
        },
        "on_call_email": {
          "nl": "ruud@bookingexperts.nl",
          "en": "ruud@bookingexperts.nl"
        },
        "name": "Ruud",
        "avatar_url": "https://dkc34q84ny7x2.cloudfront.net/uploads/user/avatar/1670/normal_ruud2bw.jpg"
      }
    }
  ]
}

Returns a list of users of the organization that are on call and have recently made a HTTP request within the Booking Experts reservation system.

List on call users for administrations

curl -g "https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/users/on_call?filter[on_call_locale]=en"
  -H "Accept: application/vnd.api+json"
  -H "Accept-Language: nl,en"
  -H "Authorization: Token $API_KEY"

Produces the following output

{
  "links": {
    "first": "https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/users/on_call?filter%5Bhelp_locale%5D=en&page%5Bnumber%5D=1",
    "self": "https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/users/on_call?filter%5Bhelp_locale%5D=en&page%5Bnumber%5D=1",
    "last": "https://api.bookingexperts.nl/v1/administrations/$ADMIN_ID/users/on_call?filter%5Bhelp_locale%5D=en&page%5Bnumber%5D=1"
  },
  "data": [
    {
      "type": "users",
      "id": "1670",
      "attributes": {
        "on_call_locales": [
          "en",
          "nl"
        ],
        "on_call_phone": {
          "nl": "0881168901",
          "en": "0881168901"
        },
        "on_call_email": {
          "nl": "ruud@bookingexperts.nl",
          "en": "ruud@bookingexperts.nl"
        },
        "name": "Ruud",
        "avatar_url": "https://dkc34q84ny7x2.cloudfront.net/uploads/user/avatar/1670/normal_ruud2bw.jpg"
      }
    }
  ]
}

Returns a list of users of the administration that are on call and have recently made a HTTP request within the Booking Experts reservation system.

Release notes

05-07-2022

21-10-2020

It is now possible to request all available custom attributes from the system. See Custom Attributes for more details. Also Tags and Custom Attributes now have a semantic tag type, which is a computer-readable type, which is chosen from a predefined list. See Semantic tag types for more information.

07-10-2020

The different links belonging to the reservation have been removed for security reasons. Only the payment link will still be available in a reservation. It is now possible to grant users access to the 'Customer portal' in which they can manage their reservations, similarly to the links which were previously in the reservation object. See customer login requests for more details.

25-05-2020

Pseudo-code that shows how to to utilize the new if_stay_starts_in attribute.

def cost_applies_to_reservation?(cost:, reservation:)
  periods = cost.if_stay_starts_in
  start_date = reservation.start_date

  if periods.contain?(start_date)
    return true # Cost applies
  else
    return false # Cost does not apply
  end
end

For the following amount, the default price is 7.5 before 01-01-2020, and 8.5 afterwards. However, for the category with ID 123 a different pricing scheme should be used. The price for this category, and only this category, is 8.5 before 01-01-2020, and 9.5 afterwards.

{
  "type": "per_guest_per_day",
  "prices": [ 7.5, "2020-01-01", 8.5],
  "category_price_overrides: {
    "123": [ 8.5, "2020-01-01", 9.5]
  },
  "class": "rent",
  "counts_guests": [ "pets" ]
}

For the following amount, the default percentage is 5.5 before 01-01-2020, and 5.55 afterwards. On the other hand, the percentage for the category with ID 123 is 6.5 before 01-01-2020, and 6.55 afterwards.

{
  "type": "percentage",
  "percentages": [ 5.5, "2020-01-01", 5.55],
  "category_percentage_overrides": {
    "123": [ 6.5, "2020-01-01", 6.55],
  }
  "over_classes": [ "rent", "defaults" ]
}

Pseudo-code that shows how to to utilize the new category_price_overrides attribute.

def prices_for_category(amount:, category:)
  overrides = amount.category_price_overrides

  if overrides[category.id]
    return overrides[category.id] # Use price overrides
  else
    return amount.prices # Use default prices
  end
end

Pseudo-code that shows how to to utilize the new category_percentage_overrides attribute.

def percentages_for_category(amount:, category:)
  overrides = amount.category_percentage_overrides

  if overrides[category.id].present?
    return overrides[category.id] # Use percentages overrides
  else
    return amount.percentages # Use default percentages
  end
end
shell