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. If children count is not 0, occupancy object will contain list ages with information about children ages:

{
  "adults": 1,
  "children": 1,
  "infants": 0,
  "ages": [5]
}

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.

ota_unique_id String. Unique room ID at OTA side. Available only for limited count of OTAs (right now only Booking.com supported).

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

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

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 support@channex.io 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:

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

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

GET https://staging.channex.io/api/v1/bookings?filter[arrival_date][gte]=2021-01-01&filter[arrival_date][lte]=2021-02-01

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:

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

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:

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

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:

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

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:

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

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:

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

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

{
  "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": "customer_email@guest.booking.com",
        "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": "VI",
        "cardholder_name": "CARDHOLDER NAME",
        "cvv": "***",
        "expiration_date": "11/2021",
        "is_virtual": false
      },
      "id": "3e029821-d446-45e9-8394-42d78a3aa1b1",
      "inserted_at": "2020-11-12T11:39:50.111087",
      "notes": null,
      "occupancy": {
        "adults": 2,
        "children": 0,
        "infants": 0
      },
      "ota_name": "BookingCom",
      "ota_reservation_code": "3333333333",
      "payment_collect": null,
      "payment_type": null,
      "property_id": "57b92389-1878-4772-9f0d-47e31d22609f",
      "revision_id": "2399140e-4673-427a-bb40-0074d917d21f",
      "rooms": [
        {
          "amount": "153.00",
          "booking_room_id": "d0f5a93b-12ba-40b5-a134-48bbf1c77532",
          "checkin_date": "2020-11-13",
          "checkout_date": "2020-11-15",
          "ota_unique_id": "49",
          "days": {
            "2020-11-13": "76.50",
            "2020-11-14": "76.50"
          },
          "guests": [
            {
              "name": "Guest Name",
              "surname": "Guest Surname"
            }
          ],
          "meta": {
            "additional_details": [],
            "booking_com_room_index": 875,
            "cancel_penalties": [
              {
                "amount": "0.00",
                "currency": "GBP",
                "from": "2020-11-09T17:32:51"
              },
              {
                "amount": "76.50",
                "currency": "GBP",
                "from": "2020-11-12T00:00:00"
              }
            ],
            "days_breakdown": [
              {
                "amount": "76.50",
                "date": "2020-11-13",
                "promotion": {
                  "id": "71591484",
                  "title": "genius rate"
                },
                "rate_code": 117855,
                "rate_plan": "785360cd-6ddb-430b-b31e-be3a2e9662a1"
              },
              {
                "amount": "76.50",
                "date": "2020-11-14",
                "promotion": {
                  "id": "71591484",
                  "title": "genius rate"
                },
                "rate_code": 117855,
                "rate_plan": "785360cd-6ddb-430b-b31e-be3a2e9662a1"
              }
            ],
            "meal_plan": "Breakfast is included in the room rate.",
            "policies": "Children and Extra Bed Policy: All children are welcome. All children under 3 years stay free of charge when using existing beds. All children from 3 to 18 years are charged  GBP 10 per night when using existing beds. There is no capacity for extra beds in the room. The maximum number of total guests in a room is 2. There is no capacity for cots in the room.  Deposit Policy: No prepayment is needed.  Cancellation Policy: The guest can cancel free of charge until 1 day before arrival. The guest will be charged the cost of the first night if they cancel within 1 day before arrival.",
            "promotion": [
              {
                "from_code": "0",
                "from_name": "genius rate",
                "promotion_id": "71591484",
                "to_code": "117855"
              }
            ],
            "rate_plan_code": 117855,
            "room_remarks": [],
            "room_type_code": "3636404",
            "smoking_preferences": null
          },
          "occupancy": {
            "adults": 2,
            "children": 0,
            "infants": 0
          },
          "rate_plan_id": "785360cd-6ddb-430b-b31e-be3a2e9662a1",
          "room_type_id": "e2a15383-7843-4240-adda-736608d72eca",
          "services": [],
          "taxes": [
            {
              "is_inclusive": true,
              "name": "VAT (5%)",
              "nights": 2,
              "persons": 2,
              "price_mode": "Per booking",
              "price_per_unit": "7.29",
              "total_price": "7.29",
              "type": "Value Added Tax (VAT)"
            }
          ]
        }
      ],
      "services": [],
      "status": "new",
      "unique_id": "BDC-3333333333"
    },
    "id": "3e029821-d446-45e9-8394-42d78a3aa1b1",
    "type": "booking"
  }
}

Airbnb examples

{
  "data": {
    "attributes": {
      "amount": "249.60",
      "ota_commission": "10.00",
      "arrival_date": "2020-09-08",
      "arrival_hour": null,
      "currency": "GBP",
      "customer": {
        "address": null,
        "city": null,
        "country": null,
        "mail": "customer_email@guest.airbnb.com",
        "name": "Name",
        "phone": "CUSTOMER PHONE",
        "surname": "Surname",
        "zip": null
      },
      "departure_date": "2020-09-11",
      "guarantee": null,
      "id": "c1620561-4a91-4a0a-8c22-7882095e3525",
      "inserted_at": "2020-08-26T20:09:28.724828",
      "notes": "Listing Base Price: 300.00\nTotal Paid Amount: 0.00\nTransient Occupancy Tax Paid Amount: 0.00\nListing Security Price: 100.00\nListing Cancellation Payout: 249.60\nListing Cancellation Host Fee: 50.40\nOccupancy Tax Amount Paid To Host: 0.00\n",
      "occupancy": {
        "adults": 1,
        "children": 0,
        "infants": 0
      },
      "ota_name": "Airbnb",
      "ota_reservation_code": "HM5MBZ1AVA",
      "payment_collect": null,
      "payment_type": null,
      "property_id": "c1620561-4a91-4c0a-8c22-7882095a4522",
      "revision_id": "54ca42b4-c4a0-4281-b6cf-c63798277dfb",
      "rooms": [
        {
          "amount": "249.60",
          "booking_room_id": "a1cce439-0e47-432a-a18a-128a16cd24f6",
          "checkin_date": "2020-09-08",
          "checkout_date": "2020-09-11",
          "days": {
            "2020-09-08": "83.20",
            "2020-09-09": "83.20",
            "2020-09-10": "83.20"
          },
          "guests": null,
          "meta": null,
          "occupancy": {
            "adults": 1,
            "children": 0,
            "infants": 0
          },
          "rate_plan_id": "c6b9777d-58b5-430d-96ea-1e5c033c3b7a",
          "room_type_id": "d8100037-fe37-452a-b4d3-a1b79ce3b049",
          "services": [],
          "taxes": []
        }
      ],
      "services": [],
      "status": "new",
      "unique_id": "ABB-HM5MBZ1AVA"
    },
    "id": "c1620561-4a91-4a0a-8c22-7882095e3525",
    "type": "booking"
  }
}

Expedia examples

{
  "data": {
    "attributes": {
      "amount": "85.00",
      "ota_commission": null,
      "arrival_date": "2021-11-10",
      "arrival_hour": null,
      "currency": "GBP",
      "customer": {
        "name": "NAME",
        "surname": "SURNAME"
      },
      "departure_date": "2021-11-11",
      "guarantee": {
        "card_number": "411111******1111",
        "card_type": "MC",
        "cardholder_name": "Expedia VirtualCard",
        "cvv": "***",
        "expiration_date": "08/2025",
        "is_virtual": true
      },
      "id": "cbb79768-3cde-4f3f-b580-86630ff04231",
      "inserted_at": "2020-09-02T10:02:32.352598",
      "notes": "Room with View please",
      "occupancy": {
        "adults": 2,
        "children": 0,
        "infants": 0
      },
      "ota_name": "A-Expedia",
      "ota_reservation_code": "1695093244",
      "payment_collect": null,
      "payment_type": null,
      "property_id": "57b12389-4878-4773-9f0d-47e31d22612a",
      "revision_id": "41913311-ac59-47e8-95e2-27cf38e7ca1b",
      "rooms": [
        {
          "amount": "85.00",
          "booking_room_id": "17334099-be2f-4c78-8692-9bd7ffd7ad32",
          "checkin_date": "2021-11-10",
          "checkout_date": "2021-11-11",
          "days": {
            "2021-11-10": "85.00"
          },
          "guests": null,
          "meta": {
            "bed_preferences": "1 Double Bed",
            "cancel_penalties": [],
            "days_breakdown": [],
            "free_text": "Room with View please",
            "payment_instruction": "Collect payment from traveler upon arrival. This Expedia virtual card can only be used in the case of a no-show or cancellation, after the booking has been reconciled. You cannot charge this card prior to reconciliation.",
            "smoking_preferences": "Non-Smoking"
          },
          "occupancy": {
            "adults": 2,
            "children": 0,
            "infants": 0
          },
          "rate_plan_id": "b835066b-233d-4c8f-a134-f291662fa34a",
          "room_type_id": "e2b23183-7843-4240-adda-736608d7becb",
          "services": [],
          "taxes": []
        }
      ],
      "services": [],
      "status": "new",
      "unique_id": "EXP-1695093244"
    },
    "id": "cbb79768-3cde-4f3f-b580-86630ff04231",
    "type": "booking"
  }
}

Reporting API

Reporting API can be used to notify OTA about some problems with current booking. At this time, we support Booking.com Reporting API (No Show, Invalid Card, Cancel Due Invalid Card).

No Show Report API

You can mark a reservation as a no-show from 00:00 (midnight, in property's local time) on the planned check-in date, up to 48 hours later, provided that:

  • the status of the reservation allows modifications;

  • the reservation isn't overbooked.

Request:

POST https://staging.channex.io/api/v1/bookings/:booking_id/no_show

Payload:

{
  "no_show_report": {
    "waived_fees": boolean
  }
}

waived_fees specifies whether the property will waive the no-show fees. Can be true or false

Invalid Card Report API

An invalid credit card can be reported immediately after the reservation is made, up until midnight (00:00) on the day of check-in, in the property's local timezone.

Request:

POST https://staging.channex.io/api/v1/bookings/:booking_id/invalid_card

Payload should be empty.

Cancel Due Invalid Card Report API

A property may cancel a reservation if the guest's credit card details are invalid and certain conditions are met:

- If you don’t receive updated credit card details within 24 hours, or the guest provides invalid credit card details again.

- For bookings made within 48 hours of check-in, if the card is invalid, the customer will have 12 hours (or until 3 pm – whichever is earlier) to update these details (instead of the usual 24 hours).

- The customer is always given at least 2 hours to update these details (i.e. if the booking is made after 2 pm on the day of arrival).

- For last-minute bookings of 10 or more room nights, partners can cancel 2 hours after marking the credit as invalid.

Request:

POST https://staging.channex.io/api/v1/bookings/:booking_id/cancel_due_invalid_card

Payload should be empty.

PreviousWebhook CollectionNextChannel API

Last updated