Channex.io
Search
⌃K

Bookings Collection

API methods to work with bookings
At Channex we have several different methods to work with Bookings, such as List of Bookings, Booking Revision Feed and etc.
Each Booking at Channex is a representation of latest known Booking Revision, where Booking Revision is parsed and normalised message from OTA.
If you would like build a PMS integration, you should use the 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 internal system
property_id ID of associated Property.
booking_id ID of associated Booking.
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.
payment_collect Information about who should collect Payment. Can be property if payment should be collected by property, ota if guest already pay at OTA and null if value is not specified. Usually null mean that property will collect payment.
payment_type Information about how payment should be collected. Can be credit_card if booking have associated credit card for payment, bank_transfer if OTA will pass payment through Bank Transfer, and null if payment type is not specified.
ota_commission Information about commission amount charged by OTA. Currently available for Booking.com and Airbnb channels.
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 value if the room is not mapped.
room_type_id Associated Room Type identification record. Null if the room is not mapped.
occupancy Object with information about Booking Room Occupancy, provide three keys: adults, children and infants.
guests List with objects of guests info. Will contain name and surname of guest if it is available for specific OTA.
services List with associated services (same as Booking Service, but at Room level).
taxes List with information about associated taxes.
amount Total Booking Room amount
days Price breakdown per day of stay. Have next structure:
"days": {
"2019-05-09": "100.00"
}
meta Free form meta information associated with room in JSON format. Can contain parent_rate_plan_id which point to real rate plan ID when booking room associated with derived rate plan or Occupancy option.

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.

Guarantee

This object represent information about credit card provided as payment guarantee.
Example:
{
"card_number": "411111******1111",
"card_type": "MC",
"cardholder_name": "Bookingcom Agent",
"cvv": "***",
"expiration_date": "12/2021",
"is_virtual": true,
"meta": {
"virtual_card_currency_code": "EUR",
"virtual_card_current_balance": "6755",
"virtual_card_decimal_places": "2",
"virtual_card_effective_date": "2020-09-12",
"virtual_card_expiration_date": "2021-09-12"
},
"token": "*****************"
}
card_number Masked credit card number
card_type Card type code. List of supported codes:
Code
Description
unknown
Card code is not exists
AX
American Express
BC
Bank Card
BL
Carte Bancaire
CU
Unionpay Credit Card
DN
Diners Club
DS
Discover Card
EL
Elo
JC
Japanese Credit Bureau Credit Card
MA
Maestro
MC
Master Card
MI
NSPK MIR
VI
Visa
cardholder_name Cardholder name
cvv Masked CVV / CVC. For non-secure connections always equal to ***
expiration_date Credit card expiration date in MM/YYYY format
is_virtual Boolean flag to represent virtual credit cards
token PCI-safety token from Channex (To be depreciated)
meta Object with additional information about credit card. Please, keep in mind, this value available only for Booking.com bookings right now and some Expedia bookings. - virtual_card_currency_code Currency of virtual credit card - virtual_card_current_balance Information about initial balance on virtual credit card. Represented as String value. - virtual_card_decimal_places Count of decimal places at provided balance value - virtual_card_effective_date Date, when virtual credit card will be active for charges - virtual_card_expiration_date Virtual credit card expiration date

Taxes

Information about Taxes associated with Booking Room.
Example:
[
{
"is_inclusive": false,
"name": "Additional Guest Fee"
"total_price": "29.57"
"type": "fee"
}
]
is_inclusive Boolean marker to show included tax into Room Price or not.
name Name of tax
total_price Total price of tax
type Represent type of tax (fee, tax, city_tax).

Notes about Guarantee details

Channex returns and receives information about Credit Card only to / from certified PCI DSS partners.
Following PCI DSS rules and security standards at industry, Channex pass PCI DSS certification and handle Credit Card information at secure mode.
If your application would like to receive information about Credit Cards you should change your target endpoint to receive bookings from staging.channex.io to secure-staging.channex.io. At production environment, you should use secure.channex.io endpoint.
Before you start use secure endpoint, please contact with us through [email protected] and provide us list of your IP address that should be white-listed and your PCI DSS certificate.

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",
"property_id": "716305c4-561a-4561-a187-7f5b8aeb5920",
"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",
"room_type_id": "994d1375-dbbd-4072-8724-b2ab32ce781b",
"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": "[email protected]",
"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",
"ota_commission: "10.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"
}
}
],
"meta": {
"page": 1,
"total": 1,
"limit": 10
}
}
Unauthorised Error Response
Status Code: 401 Unauthorized
{
"errors": {
"code": "unauthorized",
"title": "Unauthorized"
}
}

Pagination and Filters

By default, this method returns the first 10 element. To get more details, you should use Pagination arguments. Information about the count of entities and current pagination position contained at meta section at response object.

Filter Examples

Filter By Arrival Date
Filter By Departure Date
Filter By Booking Date
GET https://staging.channex.io/api/v1/bookings?filter[arrival_date][gte]=2021-01-01&filter[arrival_date][lte]=2021-02-01
GET https://staging.channex.io/api/v1/bookings?filter[departure_date][gte]=2021-01-01&filter[departure_date][lte]=2021-02-01
GET https://staging.channex.io/api/v1/bookings?filter[inserted_at][gte]=2021-01-01T00:00:00&filter[inserted_at][lte]=2021-02-01T00:00:00

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. The response will be the latest booking revision details.
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",
"room_type_id": "994d1375-dbbd-4072-8724-b2ab32ce781b",
"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": "[email protected]",
"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",
"ota_commission": "10.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",
"property_id": "716305c4-561a-4561-a187-7f5b8aeb5920",
"booking_id": "cfa33f3b-bd32-4b90-8ef9-bde2bfe986cd",
"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",
"room_type_id": "994d1375-dbbd-4072-8724-b2ab32ce781b",
"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": "[email protected]",
"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",
"ota_commission": "10.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 a list of not acknowledged booking revisions. This should be your primary way to get bookings from Channex.
When you successfully get a booking via this method make sure you acknowledge the booking. Once you have acknowledged a booking this booking revision will not be provided in the feed again.
PMS is expected to Ack all bookings from Channex. To not ack bookings for any reason will mean the booking will be consistently provided for 30 minutes and then you will receive an email warning booking was not acknowledged.
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",
"property_id": "716305c4-561a-4561-a187-7f5b8aeb5920",
"booking_id": "cfa33f3b-bd32-4b90-8ef9-bde2bfe986cd",
"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",
"room_type_id": "994d1375-dbbd-4072-8724-b2ab32ce781b",
"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": "[email protected]",
"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 will return an empty result.
If you want to get feed for a certain property you can use a filter:
GET https://staging.channex.io/api/v1/booking_revisions/feed?filter[property_id]=PROPERTY_ID
​
You can order the revisions received from feed endpoint by the oldest first.
GET https://staging.channex.io/api/v1/booking_revisions/feed?order[inserted_at]=asc

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",
"property_id": "716305c4-561a-4561-a187-7f5b8aeb5920",
"booking_id": "cfa33f3b-bd32-4b90-8ef9-bde2bfe986cd",
"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",
"room_type_id": "994d1375-dbbd-4072-8724-b2ab32ce781b",
"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": "[email protected]",
"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",
"ota_commission": "10.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 an 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.

Booking Message Examples

Booking.com examples

New Booking
Booking Modification
Booking Cancellation
{
"data": {
"attributes": {
"amount": "153.00",
"ota_commission": "10.00",
"arrival_date": "2020-11-13",
"arrival_hour": null,
"currency": "GBP",
"customer": {
"address": null,
"city": ".",
"company": null,
"country": "GB",
"language": null,
"mail": "[email protected]",
"meta": {
"is_genius": false
},
"name": "Name",
"phone": "Custom Phone",
"surname": "Surname",
"zip": null
},
"departure_date": "2020-11-15",
"guarantee": {
"card_number": "411111******1111",
"card_type"