Bookings

The bookings methods allow you to create, edit and read your bookings. Each booking contains one or many reservations.
Bookings
The required custom objects are specified in their own Objects section, complete with required fields and JSON examples. Creating and updating resources is as simple as sending in the resource using the correct HTTP method, whereas for other operations a unique id is sufficient.
When creating a Booking in production, you will need to use the following endpoint instead, which proxies the credit card details via DataTrans' PCI-Proxy service.This way PCI compliance is achieved:
​https://api.pci-proxy.com/v1/push/5775c7cf3b3e5dc0​
If you are using the Sandbox environment, you need to send the requests directly to the Katanox host using test credit cards.The rest of the requests can normally be issued using the normal Katanox host.
post
Create a booking
https://[environment].katanox.com/v1/bookings
Using this endpoint, you can create a booking consisting of one or more reservations, and Katanox will distribute them directly to the Hotels. Note that these bookings are flexible: reservations don't have to belong to the same hotel, might be spread over many different dates and contain many different guests. The booking object allows you to manage their business state in a unified way, while keeping the flexibility to modify individual reservations.
Request
Response
Request
Headers
Authorization
required
string
Bearer <api key>
Body Parameters
total_price
required
object
Total price of all reservations in the booking
customer
required
string
The Main customer of the booking
reservations
required
array
Reservation objects included in the booking
comments
optional
array
Any booking-level comments from the travel agent
payment
required
object
Payment details object
Response
200: OK
{
  "data": {
    "booking": {
      "id": "WF56HJUY",
      "total_price": {
        "amount": 218,
        "currency": "EUR"
      },
      "customer": {
        "address_line_1": "123 Street",
        "address_line_2": "",
        "city": "City",
        "country": "GB",
        "email": "[email protected]",
        "first_name": "Jorge",
        "last_name": "Doe",
        "phone": "",
        "postcode": "DE22",
        "title": "MR",
        "birth_date": "1950-01-04"
      },
      "reservations": [
        {
          "id":"1681780Y",
          "status": "accepted",
          "comments": [
            "We would like a wake up call every morning at 6am"
          ],
          "guests": [
            {
              "first_name": "John",
              "last_name": "Doe",
              "title": "MR"
            }
          ],
          "check_in": "2020-10-09",
          "check_out": "2020-10-12",
          "price": {
            "amount": 218,
            "currency": "EUR"
          },
          "rate_plan_id": "ZN8MQ5G1",
          "unit_id": "M7D2OGX9",
          "adults": 1,
          "children": 0
        }
      ],
      "comments": [
        "We will arrive around 8pm"
      ]
    }
  },
  "links": {
    "get": {
      "method": "GET",
      "url": "https://api.katanox.com/v1/bookings/WF56HJUY"
    },
    "cancel": {
      "method": "DELETE",
      "url": "https://api.katanox.com/v1/bookings/WF56HJUY"
    }
  }
}
422: Unprocessable Entity
{
    "errors": [
        "Unit OM8NXJYJ cannot be combined with Rate Plan 6KG44QGX",
        "check_in should be a future date",
        "check_out must be greater than check_in"
    ]
}
500: Internal Server Error
{
    "errors": [
        "Internal Server Error"
    ]
}
get
Retrieve a booking
https://[environment].katanox.com/v1/bookings/:id
Retrieval of a specific booking with its current state. The specific booking id is supplied to you as part of the Post method response.
Request
Response
Request
Path Parameters
id
required
string
The ID of the booking
Headers
Authorization
required
string
Bearer <api key>
Response
200: OK
{
  "data": {
    "booking": {
      "id": "9FSEI23",
      "total_price": {
        "amount": 100.58,
        "currency": "GBP"
      },
      "customer": {
        "first_name": "John",
        "last_name": "Doe",
        "title": "Mr",
        "address_line_1": "123 Imagination Street",
        "address_line_2": "Flat 4",
        "postcode": "E14 5EY",
        "city": "London",
        "country": "United Kingdom",
        "email": "[email protected]",
        "phone_number": "01234 521521",
        "birth_date": "1970-12-05"
      },
      "reservations": [
        {
          "id":"1681780Y",
          "status": "accepted",
          "comments": [
            "7am wakeup call on each day."
          ],
          "guests": [
            {
              "first_name": "John",
              "last_name": "Doe",
              "title": "Mr",
              "address_line_1": "123 Imagination Street",
              "address_line_2": "Flat 4",
              "postcode": "E14 5EY",
              "city": "London",
              "country": "United Kingdom",
              "email": "[email protected]",
              "phone_number": "01234 521521",
              "birth_date": "1970-12-05"
            }
          ],
          "check_in": "2021-05-01",
          "check_out": "2021-05-15",
          "price": {
            "amount": "100.58",
            "currency": "GBP"
          },
          "rate_plan_id": "FG3231F",
          "unit_id": "FSG424",
          "adults": "2",
          "children": "0"
        }
      ],
      "comments": [
        "a comment",
        "another comment"
      ]
    }
  },
  "links": {
    "get": {
      "method": "GET",
      "url": "https://api.katanox.com/v1/bookings/9FSEI23"
    },
    "cancel": {
      "method": "DELETE",
      "url": "https://api.katanox.com/v1/bookings/9FSEI23"
    }
  }
}
delete
Cancel a booking
https://[environment].katanox.com/v1/bookings/:id
By cancelling a booking, you are cancelling all the reservations in it.
Request
Response
Request
Path Parameters
id
required
string
The id of the booking to be cancelled
Headers
Authorization
required
string
Bearer <api key>
Response
204: No Content
​
Reservations
post
Create a reservation
https://[environment].katanox.com/v1/bookings/:id/reservations
When creating a Reservation, you must specify a Booking as a container. If there is no booking, use the Create a booking method instead.
Request
Response
Request
Path Parameters
id
required
string
The id of the booking
Headers
Authorization
required
string
Bearer <api key>
Body Parameters
comments
optional
array
Guest comments about the reservation
guests
required
array
Array of Person objects
check_in
required
string
Date (YYYY-MM-DD)
check_out
required
string
Date (YYYY-MM-DD)
price
required
object
The total price of the reservation. Refer to the Price object
rate_plan_id
required
string
The rate plan id of the reservation
unit_id
required
string
The unit id of the reservation
adults
required
integer
Number of adults in the unit
children
required
integer
Number of children in the unit
Response
200: OK
{
  "data": {
    "reservation": {
      "id": "1681780Y",
      "status": "confirmed",
      "comments": [],
      "guests": [
        {
          "first_name": "Jorge",
          "last_name": "Doe",
          "title": "MR",
          "address_line_1": "123 Street",
          "postcode": "DE22",
          "city": "City",
          "country": "GB",
          "email": "[email protected]",
          "birth_date": "1950-01-04"
        },
        {
          "first_name": "John",
          "last_name": "Doe",
          "title": "MR",
          "birth_date": "0001-01-01"
        }
      ],
      "check_in": "2020-10-09",
      "check_out": "2020-10-12",
      "price": {
        "amount": 218,
        "currency": "EUR"
      },
      "rate_plan_id": "ZN8MQ5G1",
      "unit_id": "M7D2OGX9",
      "adults": 1,
      "children": 0
    }
  },
  "links": {
    "get": {
      "method": "GET",
      "url": "https://api.katanox.com/v1/bookings/9FSEI23/reservations/1681780Y"
    },
    "cancel": {
      "method": "DELETE",
      "url": "https://api.katanox.com/v1/bookings/9FSEI23/reservations/1681780Y"
    }
  }
}
put
Update a reservation
https://[environment].katanox.com/v1/bookings/:booking_id/reservations/:reservation_id
When updating a Reservation, send in the entire reservation with its desired state. Note that this is not a partial update - all fields, specified or not, will be persisted to the existing Reservation object.
Request
Response
Request
Body Parameters
comments
optional
array
Guest comments about the reservation
guests
required
array
Array of Person objects
check_in
required
string
Date (YYYY-MM-DD)
check_out
required
string
Date (YYYY-MM-DD)
price
required
object
The total price of the reservation. Refer to the Price object
rate_plan_id
required
string
The rate plan id of the reservation
unit_id
required
string
The unit id of the reservation
adults
required
integer
Number of adults in the unit
children
required
integer
Number of children in the unit
Response
200: OK
{
  "data": {
    "reservation": {
      "id": "1681780Y",
      "status": "confirmed",
      "comments": [],
      "guests": [
        {
          "first_name": "Jorge",
          "last_name": "Doe",
          "title": "MR",
          "address_line_1": "456 Street",
          "postcode": "GE22",
          "city": "City",
          "country": "GB",
          "email": "[email protected]",
          "birth_date": "1970-01-04"
        },
        {
          "first_name": "John",
          "last_name": "Dee",
          "title": "MR",
          "birth_date": "0001-01-01"
        }
      ],
      "check_in": "2020-10-09",
      "check_out": "2020-10-12",
      "price": {
        "amount": 218,
        "currency": "EUR"
      },
      "rate_plan_id": "ZN8MQ5G1",
      "unit_id": "M7D2OGX9",
      "adults": 2,
      "children": 0
    }
  },
  "links": {
    "get": {
      "method": "GET",
      "url": "https://api.katanox.com/v1/bookings/9FSEI23/reservations/1681780Y"
    },
    "cancel": {
      "method": "DELETE",
      "url": "https://api.katanox.com/v1/bookings/9FSEI23/reservations/1681780Y"
    }
  }
}
get
Retrieve a reservation
https://[environment].katanox.com/v1/bookings/:booking_id/reservations/:reservation_id
Request
Response
Request
Path Parameters
booking_id
required
string
The ID of the booking
reservation_id
required
string
The ID of the reservation
Headers
Authorization
required
string
Bearer <api key>
Response
200: OK
{
  "data": {
    "reservation": {
      "id": "1681780Y",
      "status": "confirmed",
      "comments": [],
      "guests": [
        {
          "first_name": "Jorge",
          "last_name": "Doe",
          "title": "MR",
          "address_line_1": "456 Street",
          "postcode": "GE22",
          "city": "City",
          "country": "GB",
          "email": "[email protected]",
          "birth_date": "1970-01-04"
        },
        {
          "first_name": "John",
          "last_name": "Dee",
          "title": "MR",
          "birth_date": "0001-01-01"
        }
      ],
      "check_in": "2020-10-09",
      "check_out": "2020-10-12",
      "price": {
        "amount": 218,
        "currency": "EUR"
      },
      "rate_plan_id": "ZN8MQ5G1",
      "unit_id": "M7D2OGX9",
      "adults": 2,
      "children": 0
    }
  },
  "links": {
    "get": {
      "method": "GET",
      "url": "https://api.katanox.com/v1/bookings/9FSEI23/reservations/1681780Y"
    },
    "cancel": {
      "method": "DELETE",
      "url": "https://api.katanox.com/v1/bookings/9FSEI23/reservations/1681780Y"
    }
  }
}
delete
Cancel a reservation
https://[environment].katanox.com/v1/bookings/:booking_id/reservations/:reservation_id
Request
Response
Request
Path Parameters
booking_id
required
string
The ID of the booking
reservation_id
required
string
The ID of the reservation
Headers
Authorization
required
string
Bearer <api key>
Response
204: No Content
​
Objects
Booking object
The booking object is the container of all information related to the booking.
Fields
Example
Fields
Property
Type
Description
total_price
​Price​
Total price of all reservations
customer
​Person​
Main customer of the booking
reservations
Array of Reservations​
Reservations included in the booking
comments
Array of strings
Any comments the client wants to pass to the hotel
payment
​Payment​
Payment details object
Example
{
  "total_price": {
    "amount": 218,
    "currency": "EUR"
  },
  "customer": {
    "address_line_1": "123 Street",
    "address_line_2": "",
    "city": "City",
    "country": "GB",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "",
    "postcode": "ES22",
    "title": "MR",
    "birth_date": "1950-01-04"
  },
  "reservations": [
    {
      "comments": [
        "We would like a wake up call every morning at 6am"
      ],
      "guests": [
        {
          "first_name": "John",
          "last_name": "Doe",
          "title": "MR"
        }
      ],
      "check_in": "2020-10-09",
      "check_out": "2020-10-12",
      "price": {
        "amount": 218,
        "currency": "EUR"
      },
      "rate_plan_id": "ZN8MQ5G1",
      "unit_id": "M7D2OGX9",
      "adults": 1,
      "children": 0
    }
  ],
  "comments": [
    "We will arrive around 8pm"
  ],
  "payment": {
    "type": "visa",
    "card_number": "1234123412341234",
    "cvv": "123",
    "card_holder": "John Doe",
    "expiry_month": "08",
    "expiry_year": "2021"
  }
}
Price object
The price object provides information on the cost and currency of the transaction.
Fields
Example
Fields
Property
Type
​
Description
amount
float
required
After-tax price in the specified currency
currency
string
required
3 character ISO currency code.
Example
{
    "amount": 218,
    "currency": "EUR"
}
Person object
The person object provides information relating to the person making the purchase of the reservations. 
Fields
Example
Fields
Property
Type
Description
Required
first_name
string
​
Y
last_name
string
​
Y
title
string
​
N
birth_date
string
Format: YYYY-MM-DD
N
address_line_1
string
​
N
address_line_2
string
​
N
postcode
string
​
N
city
string
​
N
country
string
​Alpha-2 country shorthand​
N
email
string
​
N
phone_number
string
​
N
Example
{
    "address_line_1": "123 Street",
    "address_line_2": "",
    "city": "City",
    "country": "GB",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "",
    "postcode": "ES22",
    "title": "MR",
    "birth_date": "1950-01-04"
}
Reservations object
The reservations object provides information on each reservation made within the booking. 
Fields
Example
Fields
Property
Type
Description
Required
comments
Array of strings
​
N
guests
Array of Persons​
​
Y
check_in
string
Format: YYYY-MM-DD
Y
check_out
string
Format: YYYY-MM-DD
Y
price
​Price​
​
Y
rate_plan_id
string
​
Y
unit_id
string
​
Y
adults
int
Number of adults in the room
Y
children
int
Number of children in the room
Y
status
Enum(Confirmed, Processing, Cancelled)
returned as part of all responses that include reservations
N
Example
{
  "reservation": {
      "id": "1681780Y",
      "status": "confirmed",
      "comments": [],
      "guests": [
        {
          "first_name": "Jorge",
          "last_name": "Doe",
          "title": "MR",
          "address_line_1": "123 Street",
          "postcode": "DE22",
          "city": "City",
          "country": "GB",
          "email": "[email protected]",
          "birth_date": "1950-01-04"
        },
        {
          "first_name": "John",
          "last_name": "Doe",
          "title": "MR",
          "birth_date": "0001-01-01"
        }
      ],
      "check_in": "2020-10-09",
      "check_out": "2020-10-12",
      "price": {
        "amount": 218,
        "currency": "EUR"
      },
      "rate_plan_id": "ZN8MQ5G1",
      "unit_id": "M7D2OGX9",
      "adults": 1,
      "children": 0
    }
  }
}
Payment object
The payment object provides the information required to process payment for the booking.
Fields
Example
Fields
Property
Type
Description
Required
type
string
enum(VISA, MASTERCARD, AMERICAN_EXPRESS)
Y
card_number
string
​
Y
cvv
string
​
Y
card_holder
string
​
Y
expiry_month
string
2-number format (e.g. for August enter 08)
Y
expiry_year
string
4-number format (e.g. 2022)
Y
Example
{
    "type": "visa",
    "card_number": "1234123412341234",
    "cvv": "123",
    "card_holder": "John Doe",
    "expiry_month": "08",
    "expiry_year": "2021"
}
API Documentation - Previous
Availability
Next - API Documentation
Properties
Last updated 2 months ago
Property	Type	Description
`total_price`	Price	Total price of all reservations
`customer`	Person	Main customer of the booking
`reservations`	Array of Reservations	Reservations included in the booking
`comments`	Array of strings	Any comments the client wants to pass to the hotel
`payment`	Payment	Payment details object
Bookings

Bookings

postCreate a booking

getRetrieve a booking

deleteCancel a booking

Reservations

postCreate a reservation

putUpdate a reservation

getRetrieve a reservation

deleteCancel a reservation

Objects

Booking object

Price object

Person object

Reservations object

Payment object

post
Create a booking

get
Retrieve a booking

delete
Cancel a booking

post
Create a reservation

put
Update a reservation

get
Retrieve a reservation

delete
Cancel a reservation
