Guides
OpenAPI SpecHolidu WhitelabelsPartner PortalHolidu

Booking notification

Suggest Edits

This endpoint should be implemented by partners connecting to Holidu’s API and willing to have their properties bookable on Holidu.

Holidu will send a request to notify the partners when one of their properties is booked. The partners need to register the booking in their system and confirm the receiving of the booking. There needs to be a unique transaction id for any successful transmitted booking provided by the partner in the response to the request.

❗️

Please only accept bookings if the total price in the booking notification matches the price in your system. Due to some configuration errors or time delays it can be possible to have price differences between your prices and the prices shown on holidu, BUT the customer books the property based on the prices shown on holidu. In order to avoid customer complaints and cancelled bookings, please reject bookings with a wrong price directly.

BookingNotification Request

It is a POST request with the following parameters:

Field Type Required Content
bookingId string true Booking ID created by Holidu
externalId string true Your Identifier + Apartment ID in your system (see example below)
arrival LocalDate:
YYYY-MM-DD		 true When the customer would check in
departure LocalDate:
YYYY-MM-DD		 true When the customer would check out
guests Array of Guest objects true List of guests
gender string:
male
female		 true Gender
firstName string true First name
lastName string true Last name
street string true Name of the street
zip string true Zip code
city string true City
country string:
DE, FR, US, GB, etc.		 true Country of the user (ISO 3166-2)
phone string true Phone number
email string true Email address
comment string optional Special request or comment
extraServices Array of ExtraService objects optional List of extra services included in the final price (selected options)
price Price object optional Final price including all the mandatory and selected extra costs but without Tourist Tax
paymentMethod string:
BANK_TRANSFER, INVOICE, VISA, CREDIT_CARD, MAESTRO, PAYPAL, MASTER_CARD, AMERICAN_EXPRESS, JAPAN_CREDIT_BUREAU, DINERS_CLUB, MASTERPASS		 true The payment method selected by the customer
paymentRates Array of payment rates optional The payment rates calculated as per configuration
currency string:
EUR, USD, GBP, etc.		 true User’s currency (ISO 4217)
language string:
de, fr, en, etc.		 true Language that the customer speaks (ISO 639-1)
costs Array of Mandatory Cost objects optional List of mandatory costs pushed to Holidu

Guest object
Each guest is represented by a guest object containing information about him.

Field Type Required Content
age integer true The age of this guest

ExtraService object
Information about selected option or mandatory costs included in the total price.

Field Type Required Content
serviceId string true Id of the service you provide in our API
quantity integer true Quantity selected by the guest
label string true Name of the service you provide

Price object
Price information in both original and user’s currency. They can be the same if the user uses the original currency.

Field Type Required Content
value number (BigDecimal) true Price in user’s currency
currency string:
EUR, USD, GBP, etc.		 true User’s currency (ISO 4217)
originalValue number (BigDecimal) true Price in original currency
originalCurrency string:
EUR, USD, GBP, etc.		 true Original currency (ISO 4217)

Payment rates object

Field Type Required Content
price Price object true Total price due on date
dueDate string true Date on which the payment is due, pattern: yyyy-MM-dd
percentage number (BigDecimal) true Percentage of total price which is due

Cost object

Field Type Required Content
serviceId String true Id of the cost in our API
label String true Name of the cost in our API
description String true Description of the cost
costType String:
MANDATORY_EXCLUDED_FROM_BASE_PRICE		 true Type of cost.
costUnit String:
PER_NIGHT, PER_TWO_NIGHTS, PER_DAY, PER_WEEK, PER_MONTH, PER_STAY, PER_PERSON, PER_PERSON_PER_NIGHT, PER_PERSON_PER_TWO_NIGHTS, PER_PERSON_PER_DAY, PER_PERSON_PER_WEEK, PER_PET, PER_PET_PER_NIGHT, PER_PET_PER_DAY, PER_PET_PER_WEEK, PER_UNIT, PER_PERCENTAGE		 true Unit at which the cost is charged.
pricePerUnit Price object true Price per unit of the cost
totalPrice Price object optional Total price of the cost based on calculations
paymentDueDate String true Date on which the payment is due, pattern: yyyy-MM-dd
paymentTime String:
WITH_BASE_PRICE, ON_ARRIVAL, ON_DEPARTURE, ON_DATE, ON_SITE		 true Time at which the payment for the cost is expected.
maximumCount integer true Maximum count of the cost that is possible
minimumCount integer true Minimum count of the cost that is possible
conditions Array of Condition object optional Conditions that are applicable to the cost. See Condition object below.

Condition object

Field Type Required Content
type String:
PRICE_RANGE, VALIDITY_PERIOD, NUMBER_OF_NIGHTS, NUMBER_OF_PEOPLE, AGE_OF_PERSON		 true The type of condition on which the cost is applied
from string true Start range of the condition
to string true End range of the condition

Example booking notification

{
 "bookingId": "eacf97a4-cba2-4db1-8c02-d69306fc369f",
 "externalId": "PROVIDER-623730",
 "arrival": "2018-12-07",
 "departure": "2018-12-10",
 "guests": [
   {
     "age": 18
   },
   {
     "age": 18
   }
 ],
 "gender": "male",
 "firstName": "Test1 2",
 "lastName": "Test 2 3 4",
 "street": "Teststreet 24",
 "zip": "80992",
 "city": "München",
 "country": "DE",
 "phone": "000000000000",
 "email": "[email protected]",
 "comment": "TEST booking, please cancel",
 "extraServices": [
   {
     "serviceId": "110_fac_xb",
     "providerServiceId":"3344-abba",
     "quantity": 1,   
     "label": "Haustier"
   },
   {
     "serviceId": "111_fac_xb",
     "providerServiceId":"3345-abba",
     "quantity": 2,
     "label": "Bettwäsche"
   }
 ],
 "price": {
   "value": 1820.00,
   "currency": "EUR",
   "originalValue": 1820.00,
   "originalCurrency": "EUR"
 },
 "paymentMethod": "BANK_TRANSFER",
 "paymentRates":[
      {
         "price":{
            "value":588.00,
            "currency":"EUR",
            "originalValue":588.00,
            "originalCurrency":"EUR"
         },
         "dueDate":"2020-12-17"
      },
      {
         "price":{
            "value":1372.00,
            "currency":"EUR",
            "originalValue":1372.00,
            "originalCurrency":"EUR"
         },
         "dueDate":"2021-03-05"
      }
   ],
 "currency": "EUR",
 "language": "de",  
  
 "costs": [
   {
     "serviceId": "111_109918759",
     "label": "CLEANING",
     "costType": "MANDATORY_EXCLUDED_FROM_BASE_PRICE",
     "costUnit": "PER_STAY",
     "pricePerUnit": {
       "value": 100,
       "currency": "EUR",
       "originalValue": 100,
       "originalCurrency": "EUR"
     },
     "totalPrice": {
       "value": 100,
       "currency": "EUR",
       "originalValue": 100,
       "originalCurrency": "EUR"
     },
     "paymentTime": "WITH_BASE_PRICE",
     "maximumCount": 1,
     "conditions": []
   }
 ],
"brand":"HOLIDU"
}

Booking response body

Field Type Required Content
errorCode Integer optional Error code. Required in case of a failed booking.
errorMessage String optional Error message as a String. Required in case of failed booking.
transactionId String optional Transaction/Booking Id generated in your system. Required in case of successful booking.
status String true Status of the booking request. It should be one of eitherCONFIRMED, FAILED
paymentUrl String optional This lets you return an URL to which the user can pay its booking. We will show this URL on the confirmation page, and on the confirmation email.

Example Responses

{
 "transactionId": "123456789",
 "status": "CONFIRMED",
 "paymentUrl" : "https://PAYMENT_LINK.com"
}

{
 "errorCode": XXX,
 "errorMessage": "Please specify the error"
 "status": "FAILED"
}

❗️

Please make sure you send the correct http status in the response. Any response with a response code of 200 will be handled as a confirmed booking independent on any errorCode or errorMessage in the response.

👍

For security measures we recommend you to whitelist our IPs so that we can only do requests to you from the following IPs:

  • 54.77.51.111
  • 34.249.124.33
  • 212.114.208.106
  • 99.80.89.251
  • 34.242.187.158
  • 34.250.93.237

Updated about 2 years ago