Bookings Collection

API methods to work with bookings

At Channex.io we have several different methods to work with Bookings, such as List of Bookings, Booking Revision Feed and etc.

Each Booking at Channex.io is representation of latest known Booking Revision, where Booking Revision is parsed and normalised message from OTA.

If you would like build PMS integration, you should use Booking Revision Feed API, to fetch booking messages and modify bookings at your side. For initial pull, you can use Booking List API or Booking Revision Feed.

Message Structures

Booking Revision

id Unique Booking Revision identification record at Channex.io internal system

unique_id Unique Booking identification record combined from OTA Code and OTA Reservation Code. Usually this value is same for all booking revisions.

system_id Unique message identification record at Booking Source platform, unique per revision. Used to detect have we that message or not.

ota_reservation_code Original Reservation Code at platform, where guest create booking. Usually same for all booking revisions. Unique per booking message.

ota_name Name of OTA where booking was originally created

status Status of Booking Revision, can be one of three values: new, modified, cancelled.

rooms List of Booking Room objects.

services List of Booking Service objects.

guarantee Guarantee details object. Represent credit card provided with booking.

customer Object with information about Customer.

occupancy Object with information about total Booking Occupancy, provide three keys: adults, children and infants.

arrival_date Arrival Date represented as string with date in ISO 8601 format by mask YYYY-MM-DD.

departure_date Departure Date represented as string with date in ISO 8601 format by mask YYYY-MM-DD.

arrival_hour Arrival Time represented as string with time in HH:MM format at 24h.

amount Total booking amount.

currency Booking currency code.

notes Customer notes for booking.

inserted_at Timestamp, when Booking Revision was received at Channex.io

Booking Room

checkin_date Checkin Date represented as string with date in ISO 8601 format by mask YYYY-MM-DD.

checkout_date Checkout Date represented as string with date in ISO 8601 format by mask YYYY-MM-DD.

rate_plan_id Associated Rate Plan identification record. Null if Booking Room is not mapped.

occupancy Object with information about Booking Room Occupancy, provide three keys: adults, children and infants.

amount Total Booking Room amount

Booking Service

name String value with service name in English language

nights Integer value represents number of nights this customer has booked the service for.

persons Integer number represents number of persons this service is booked for

price_mode String value with Price mode value (per stay, per night, per person per night).

price_per_unit Numeric value represented as String with unitary price for this service

total_price Numeric value represented as String with total calculated price for this service.

Bookings List

Retrieve list of Bookings associated with User Channels.

Request
Success Response
Error Response

Request:

GET https://staging.channex.io/api/v1/bookings

Success Response Example

Status Code: 200 OK

{
"meta": {
"total": 1,
"page": 1,
"limit": 10
},
"data": [
{
"type": "booking",
"id": "603e8e9e-cc67-4ca7-bd13-3c407c6c3bbd",
"attributes": {
"id": "603e8e9e-cc67-4ca7-bd13-3c407c6c3bbd",
"revision_id": "03dd7198-c5b7-493c-a889-74d0c2211de7",
"unique_id": "BDC-1556013801",
"ota_reservation_code": "1556013801",
"ota_name": "Booking.com",
"status": "new",
"rooms": [
{
"amount": "200.00",
"checkin_date": "2019-04-26",
"checkout_date": "2019-04-27",
"rate_plan_id": "445835fb-7956-42ac-9efc-3e6f331f0808",
"days": {
"2019-04-26": "200.00"
},
"occupancy": {
"adults": 2,
"children": 0,
"infants": 0
}
}
],
"services": [
{
"type": "Breakfast",
"total_price": "20.00",
"price_per_unit": "10.00",
"price_mode": "Per person per night",
"persons": 2,
"nights": 1,
"name": "Breakfast"
}
],
"guarantee": {
"expiration_date": "10/2020",
"cvv": "***",
"cardholder_name": "Channex User",
"card_type": "visa",
"card_number": "411111******1111"
},
"customer": {
"zip": "2031 BE",
"surname": "Channex",
"phone": "1234567890",
"name": "User",
"mail": "user@channex.io",
"language": "en",
"country": "NL",
"city": "Haarlem",
"address": "JW Lucasweg 35"
},
"occupancy": {
"adults": 2,
"children": 0,
"infants": 0
},
"arrival_date": "2019-04-26",
"departure_date": "2019-04-27",
"arrival_hour": "10:00",
"amount": "220.00",
"currency": "GBP",
"notes": "You have a booker that would like free parking. (based on availability)\nYou have a booker that would prefer a quiet room. (based on availability)",
"inserted_at": "2019-04-23T10:03:29.335485"
}
}
]
}

Unauthorised Error Response

Status Code: 401 Unauthorized

{
"errors": {
"code": "unauthorized",
"title": "Unauthorized"
}
}

Returns

Success Method can return a Success result with 200 OK HTTP Code if operation is successful. Will contain a list of Booking objects in the answer. Unauthorised Error Method can return a Unauthorised Error result with 401 Unauthorized HTTP Code if wrong Bearer Token provided.

Get Booking By ID

Retrieve specific Booking by ID.

Request
Success Response
Error Response

Request:

GET https://staging.channex.io/api/v1/bookings/:id

Success Response Example

Status Code: 200 OK

{
"data": {
"type": "booking",
"id": "603e8e9e-cc67-4ca7-bd13-3c407c6c3bbd",
"attributes": {
"id": "603e8e9e-cc67-4ca7-bd13-3c407c6c3bbd",
"revision_id": "03dd7198-c5b7-493c-a889-74d0c2211de7",
"unique_id": "BDC-9996013801",
"ota_reservation_code": "9996013801",
"ota_name": "Booking.com",
"status": "new",
"rooms": [
{
"amount": "200.00",
"checkin_date": "2019-04-26",
"checkout_date": "2019-04-27",
"rate_plan_id": "445835fb-7956-42ac-9efc-3e6f331f0808",
"days": {
"2019-04-26": "200.00"
},
"occupancy": {
"adults": 2,
"children": 0,
"infants": 0
}
}
],
"services": [
{
"type": "Breakfast",
"total_price": "20.00",
"price_per_unit": "10.00",
"price_mode": "Per person per night",
"persons": 2,
"nights": 1,
"name": "Breakfast"
}
],
"guarantee": {
"expiration_date": "10/2020",
"cvv": "***",
"cardholder_name": "Channex User",
"card_type": "visa",
"card_number": "411111******1111"
},
"customer": {
"zip": "2031 BE",
"surname": "Channex",
"phone": "1234567890",
"name": "User",
"mail": "user@channex.io",
"language": "en",
"country": "NL",
"city": "Haarlem",
"address": "JW Lucasweg 35"
},
"occupancy": {
"adults": 2,
"children": 0,
"infants": 0
},
"arrival_date": "2019-04-26",
"departure_date": "2019-04-27",
"arrival_hour": "10:00",
"amount": "220.00",
"currency": "GBP",
"notes": "You have a booker that would like free parking. (based on availability)\nYou have a booker that would prefer a quiet room. (based on availability)",
"inserted_at": "2019-04-23T10:03:29.335485"
}
}
}

Unauthorised Error Response

Status Code: 401 Unauthorized

{
"errors": {
"code": "unauthorized",
"title": "Unauthorized"
}
}

Not Found Error

Status Code: 404 Not Found

{
"errors": {
"code": "not_found",
"title": "Resouce Not Found"
}
}

Returns

Success Method can return a Success result with 200 OK HTTP Code if operation is successful. Will contain a Booking object in the answer. Unauthorised Error Method can return a Unauthorised Error result with 401 Unauthorized HTTP Code if wrong Bearer Token provided.

Not Found Error Method can return a Not Found Error result with 404 Not Found HTTP Code if Booking with provided ID is not present at system.

Booking Revisions List

Retrieve list of Booking Revisions associated with User Channels.

Request
Success Response
Error Response

Request:

GET https://staging.channex.io/api/v1/booking_revisions

Success Response Example

Status Code: 200 OK

{
"meta": {
"total": 1,
"page": 1,
"limit": 10
},
"data": [
{
"type": "booking_revision",
"id": "03dd7198-c5b7-493c-a889-74d0c2211de7",
"attributes": {
"id": "03dd7198-c5b7-493c-a889-74d0c2211de7",
"unique_id": "BDC-9996013801",
"system_id": "12331233123",
"ota_reservation_code": "9996013801",
"ota_name": "Booking.com",
"status": "new",
"rooms": [
{
"amount": "200.00",
"checkin_date": "2019-04-26",
"checkout_date": "2019-04-27",
"rate_plan_id": "445835fb-7956-42ac-9efc-3e6f331f0808",
"days": {
"2019-04-26": "200.00"
},
"occupancy": {
"adults": 2,
"children": 0,
"infants": 0
}
}
],
"services": [
{
"type": "Breakfast",
"total_price": "20.00",
"price_per_unit": "10.00",
"price_mode": "Per person per night",
"persons": 2,
"nights": 1,
"name": "Breakfast"
}
],
"guarantee": {
"expiration_date": "10/2020",
"cvv": "***",
"cardholder_name": "Channex User",
"card_type": "visa",
"card_number": "411111******1111"
},
"customer": {
"zip": "2031 BE",
"surname": "Channex",
"phone": "1234567890",
"name": "User",
"mail": "user@channex.io",
"language": "en",
"country": "NL",
"city": "Haarlem",
"address": "JW Lucasweg 35"
},
"occupancy": {
"adults": 2,
"children": 0,
"infants": 0
},
"arrival_date": "2019-04-26",
"departure_date": "2019-04-27",
"arrival_hour": "10:00",
"amount": "220.00",
"currency": "GBP",
"notes": "You have a booker that would like free parking. (based on availability)\nYou have a booker that would prefer a quiet room. (based on availability)",
"inserted_at": "2019-04-23T10:03:29.335485"
}
}
]
}

Unauthorised Error Response

Status Code: 401 Unauthorized

{
"errors": {
"code": "unauthorized",
"title": "Unauthorized"
}
}

Returns

Success Method can return a Success result with 200 OK HTTP Code if operation is successful. Will contain a list of Booking Revision objects in the answer. Unauthorised Error Method can return a Unauthorised Error result with 401 Unauthorized HTTP Code if wrong Bearer Token provided.

Booking Revisions Feed

Retrieve list of not Acknowledged Booking Revisions associated with User Channels.

Request
Success Response
Error Response

Request:

GET https://staging.channex.io/api/v1/booking_revisions/feed

Success Response Example

Status Code: 200 OK

{
"meta": {
"total": 1,
"page": 1,
"limit": 10
},
"data": [
{
"type": "booking_revision",
"id": "03dd7198-c5b7-493c-a889-74d0c2211de7",
"attributes": {
"id": "03dd7198-c5b7-493c-a889-74d0c2211de7",
"unique_id": "BDC-9996013801",
"system_id": "12331233123",
"ota_reservation_code": "9996013801",
"ota_name": "Booking.com",
"status": "new",
"rooms": [
{
"amount": "200.00",
"checkin_date": "2019-04-26",
"checkout_date": "2019-04-27",
"rate_plan_id": "445835fb-7956-42ac-9efc-3e6f331f0808",
"days": {
"2019-04-26": "200.00"
},
"occupancy": {
"adults": 2,
"children": 0,
"infants": 0
}
}
],
"services": [
{
"type": "Breakfast",
"total_price": "20.00",
"price_per_unit": "10.00",
"price_mode": "Per person per night",
"persons": 2,
"nights": 1,
"name": "Breakfast"
}
],
"guarantee": {
"expiration_date": "10/2020",
"cvv": "***",
"cardholder_name": "Channex User",
"card_type": "visa",
"card_number": "411111******1111"
},
"customer": {
"zip": "2031 BE",
"surname": "Channex",
"phone": "1234567890",
"name": "User",
"mail": "user@channex.io",
"language": "en",
"country": "NL",
"city": "Haarlem",
"address": "JW Lucasweg 35"
},
"occupancy": {
"adults": 2,
"children": 0,
"infants": 0
},
"arrival_date": "2019-04-26",
"departure_date": "2019-04-27",
"arrival_hour": "10:00",
"amount": "220.00",
"currency": "GBP",
"notes": "You have a booker that would like free parking. (based on availability)\nYou have a booker that would prefer a quiet room. (based on availability)",
"inserted_at": "2019-04-23T10:03:29.335485"
}
}
]
}

Unauthorised Error Response

Status Code: 401 Unauthorized

{
"errors": {
"code": "unauthorized",
"title": "Unauthorized"
}
}

Note

If all Booking Revision is acknowledged this request return empty result.

Returns

Success Method can return a Success result with 200 OK HTTP Code if operation is successful. Will contain a list of Booking Revision objects in the answer. Unauthorised Error Method can return a Unauthorised Error result with 401 Unauthorized HTTP Code if wrong Bearer Token provided.

Get Booking Revision by ID

Retrieve specific Booking Revision by ID.

Request
Success Response
Error Response

Request:

GET https://staging.channex.io/api/v1/booking_revisions/:id

Success Response Example

Status Code: 200 OK

{
"data": {
"type": "booking_revision",
"id": "03dd7198-c5b7-493c-a889-74d0c2211de7",
"attributes": {
"id": "03dd7198-c5b7-493c-a889-74d0c2211de7",
"unique_id": "BDC-9996013801",
"system_id": "12331233123",
"ota_reservation_code": "9996013801",
"ota_name": "Booking.com",
"status": "new",
"rooms": [
{
"amount": "200.00",
"checkin_date": "2019-04-26",
"checkout_date": "2019-04-27",
"rate_plan_id": "445835fb-7956-42ac-9efc-3e6f331f0808",
"days": {
"2019-04-26": "200.00"
},
"occupancy": {
"adults": 2,
"children": 0,
"infants": 0
}
}
],
"services": [
{
"type": "Breakfast",
"total_price": "20.00",
"price_per_unit": "10.00",
"price_mode": "Per person per night",
"persons": 2,
"nights": 1,
"name": "Breakfast"
}
],
"guarantee": {
"expiration_date": "10/2020",
"cvv": "***",
"cardholder_name": "Channex User",
"card_type": "visa",
"card_number": "411111******1111"
},
"customer": {
"zip": "2031 BE",
"surname": "Channex",
"phone": "1234567890",
"name": "User",
"mail": "user@channex.io",
"language": "en",
"country": "NL",
"city": "Haarlem",
"address": "JW Lucasweg 35"
},
"occupancy": {
"adults": 2,
"children": 0,
"infants": 0
},
"arrival_date": "2019-04-26",
"departure_date": "2019-04-27",
"arrival_hour": "10:00",
"amount": "220.00",
"currency": "GBP",
"notes": "You have a booker that would like free parking. (based on availability)\nYou have a booker that would prefer a quiet room. (based on availability)",
"inserted_at": "2019-04-23T10:03:29.335485"
}
}
}

Unauthorised Error Response

Status Code: 401 Unauthorized

{
"errors": {
"code": "unauthorized",
"title": "Unauthorized"
}
}

Not Found Error

Status Code: 404 Not Found

{
"errors": {
"code": "not_found",
"title": "Resouce Not Found"
}
}

Returns

Success Method can return a Success result with 200 OK HTTP Code if operation is successful. Will contain a Booking Revision object in the answer. Unauthorised Error Method can return a Unauthorised Error result with 401 Unauthorized HTTP Code if wrong Bearer Token provided.

Not Found Error Method can return a Not Found Error result with 404 Not Found HTTP Code if Booking Revision with provided ID is not present at system.

Acknowledge Booking Revision receiving

Confirm receiving Booking Revision by creating Acknowledge record.

Request
Success Response
Error Response

Request:

POST https://staging.channex.io/api/v1/booking_revisions/:id/ack

Success Response Example

Status Code: 200 OK

{
"meta": {
"message": "Success"
}
}

Unauthorised Error Response

Status Code: 401 Unauthorized

{
"errors": {
"code": "unauthorized",
"title": "Unauthorized"
}
}

Not Found Error

Status Code: 404 Not Found

{
"errors": {
"code": "not_found",
"title": "Resouce Not Found"
}
}

Returns

Success Method can return a Success result with 200 OK HTTP Code if operation is successful. Unauthorised Error Method can return a Unauthorised Error result with 401 Unauthorized HTTP Code if wrong Bearer Token provided.

Not Found Error Method can return a Not Found Error result with 404 Not Found HTTP Code if Booking Revision with provided ID is not present at system.

Create Booking

API to push Booking into Channex.io.

NOTE: Before create booking through API, you should create Booking Engine Channel at Channel Management screen of application. Then use created Channel ID as channel_id at new booking message.

Request
Success Response
Error Response

Request:

POST https://staging.channex.io/api/v1/bookings/push

Query body (JSON):

{
"booking": {
"status": "commit",
"channel_id": "677fb5f8-d7d7-4a65-a3e4-bf0c8777b6dc",
"reservation_id": "162",
"arrival_date": "2019-05-09",
"departure_date": "2019-05-10",
"arrival_hour": "10:00",
"currency": "GBP",
"customer": {
"name": "Andrew",
"surname": "Yudin"
},
"rooms": [
{
"occupancy": {
"adults": 1,
"children": 0,
"infants": 0
},
"rate_plan_id": "f0a84d15-c36f-487c-9c8d-a7f907224a24",
"days": {
"2019-05-09": 10000
}
}
]
}
}

Success Response Example

Status Code: 200 OK

{
"data": {
"type": "booking",
"id": "c172bf2d-eefe-471a-b4b0-0d156a766b79",
"attributes": {
"unique_id": "CBE-162",
"status": "cancelled",
"services": [],
"rooms": [
{
"rate_plan_id": "f0a84d15-c36f-487c-9c8d-a7f907224a24",
"occupancy": {
"infants": 0,
"children": 0,
"adults": 1
},
"departure_date": "2019-05-10",
"days": {
"2019-05-09": "100.00"
},
"arrival_date": "2019-05-09",
"amount": "100.00"
}
],
"revision_id": "49f55f9a-d19f-470a-818a-779aa6740af2",
"ota_reservation_code": "162",
"ota_name": null,
"occupancy": {
"infants": 0,
"children": 0,
"adults": 1
},
"notes": null,
"inserted_at": "2019-05-01T08:35:28.607625",
"id": "c172bf2d-eefe-471a-b4b0-0d156a766b79",
"guarantee": null,
"departure_date": "2019-05-10",
"customer": {
"zip": null,
"surname": "Yudin",
"phone": null,
"name": "Andrew",
"mail": null,
"language": null,
"country": null,
"city": null,
"address": null
},
"currency": "GBP",
"arrival_hour": "10:00",
"arrival_date": "2019-05-09",
"amount": "100.00"
}
}
}

Unauthorised Error Response

Status Code: 401 Unauthorized

{
"errors": {
"code": "unauthorized",
"title": "Unauthorized"
}
}

Not Found Error

Status Code: 404 Not Found

{
"errors": {
"code": "not_found",
"title": "Resouce Not Found"
}
}

Returns

Success Method can return a Success result with 200 OK HTTP Code if operation is successful. Body will contain created booking. Unauthorised Error Method can return a Unauthorised Error result with 401 Unauthorized HTTP Code if wrong Bearer Token provided.

Not Found Error Method can return a Not Found Error result with 404 Not Found HTTP Code if Booking Revision with provided ID is not present at system.