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"
}