Hotel Service Change Notification v4
The Hotel Service Change Notification API allows Custom Hotel Source (CHS) suppliers to provide the SAP Concur platform with details of offline cancellations and changes they make to bookings created in the SAP Concur Online Booking tool (OBT). The API allows CHS vendors to provide updates in real time so that travelers have the most up-to-date information about their booking.
Change Notification API also provides a way to confirm hotels/accommodations that are not available in any online booking management system - and manual intervention is required to do the fulfillment. Example of such accommodations are corporate apartments, specialty hotels, etc. Such hotels are marked as OnRequest for a HotelProperty in search response.
Limitations
Access to this documentation does not provide access to the API. SAP Concur products are highly configurable, and not all clients will have access to all features.
Process Flow
Flow diagram below depicts various use cases supported by the Change Notification API.
- User goes through regular hotel booking process in the OBT. If hotel is marked as
OnRequest- it is clearly indicated to user during booking suggesting that the booking confirmation will not be available immediately. - If user books an
OnRequesthotel, booking will be created withPendingstatus. Status will be transitioned toRESERVEDonce it is confirmed by supplier usingChange Notification APIendpoint (usingchangeTypeCodeasUPDATE). - If booking is
cancelledoffline, supplier can callChange Notification APIwithchangeTypeCodeasCANCELand trigger cancellation of previously booked hotel booking in Concur OBT. - If booking is
Replacedoffline, supplier can callChange Notification APIwithchangeTypeCodeasREPLACEand previously booked hotel is canceled while a replaced hotel is added in the OBT. - Supplier can also use
Change Notification APIfor other offline changes to previously used hotel booking. For example, check-in/check-out dates, room rate etc. or add a new booking altogether on existing trip.
Products and Editions
- Concur Travel Professional Edition
- Concur Travel Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
travel.hotel.write |
Read and update hotel bookings | POST |
Dependencies
CHS partner interesting in using this API must have implemented Hotel Service v4 API and integrated hotel shop and book flows with SAP Concur OBT using their Connector.
Access Token Usage
- Each CHS supplier planning to use this API will need to request access to register a client application with the SAP Concur platform. If a supplier already has a client application registered, this step can be skipped.
clientIdandclientSecretobtained here need to be used for client credentials grant based auth as described here. - Suppliers will need to have the
travel.hotel.writescope in the application access they request above. API implementation verifies the presence of this scope in JWT before allowing access.
Authorization
Change Notification API can only be used to add/update bookings by authorized CHS suppliers. Authorization is controlled by matching clientId of your client application for each environment with Hotel Service Connector already established with the SAP Concur platform. Therefore, to gain access, clientId for your application must be provided to the SAP Concur team working with you.
Association of clientId to Connector is then used to enforce the following authorization rules:
- For existing bookings, a given client/partner can only update/replace bookings created by their connector.
- For new bookings, a given client/partner’s connector must be enabled on the SAP Concur travel configuration used by Trip.
Change Notification Endpoint
This endpoint allows CHS suppliers to update, cancel/replace or add new hotel booking on existing trip. tripId must be already known and any existing bookings can be updated only if supplier is the source for the booking.
Schema
The schema is available at: Direct Connect - Hotel Service v4 - Schemas.
URI
https://{datacenterURI}/travel/v4/trips/{tripId}/hotels/change-notification:
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
tripId |
string |
- | Required ID of user trip/itinerary that contains booking(s) that needs to be updated. |
Examples
Below are examples of JSON payloads that can be sent to the endpoint to update, cancel/replace, or add new hotel booking on an existing trip.
Add booking to existing trip.
{
"changeId": "00000000-0000-0000-0000-000000000000",
"changeTimestamp": "2024-04-30T12:26:18-05:00",
"changeTypeCode": "ADD",
"updatedBookings": [
{
"basicHotelProperty": {
"address": {
"addressLines": [
"line 1",
"line 2"
],
"city": "dummy city",
"countryCode": "dummy country code",
"postalCode": "dummy postal code",
"state": "dummy state",
"stateName": "dummy state name"
},
"chainCode": "dummy chain code",
"cityCode": "dummy city code",
"contactInfo": {
"emails": [
"someone@somewhere.com"
],
"faxNumber": "000",
"phoneNumbers": [
"000",
"000"
]
},
"hotelName": "dummy hotel name",
"position": {
"latitude": 0,
"longitude": 0
},
"propertyCode": "dummy property code"
},
"checkin": "2024-04-30",
"checkout": "2024-05-03",
"confirmationCodes": [
{
"code": "dummy supplier confirmation code",
"codeType": "SUPPLIER_CONFIRMATION"
}
],
"guests": [
{
"address": {
"addressLines": [
"123 Green St",
""
],
"city": "Albuquerque",
"countryCode": "US",
"postalCode": "87104",
"state": "New Mexico"
},
"birthdate": "1959-09-07",
"companyName": "Best Company Ever",
"contactInfo": {
"emails": [
"w@w.com"
],
"faxNumber": "000",
"phoneNumbers": [
"000"
]
},
"firstname": "John",
"lastname": "Smith"
}
],
"isModifiable": true,
"roomRate": {
"cancelPenalties": {
"penalties": [
{
"amountPercent": {
"amount": {
"amount": 100,
"currencyCode": "USD"
},
"applyAs": "FIRST_AND_LAST_NIGHT_DEPOSIT",
"basisType": "FULL_STAY",
"feesInclusive": true,
"numberOfNights": 3,
"percent": 99,
"taxInclusive": true
},
"cancelDeadline": "2018-10-10T19:10:59Z",
"description": "\u003cb\u003edummy description\u003c/b\u003e",
"refundableStatus": "FULLY_REFUNDABLE"
},
{
"cancelDeadline": "2018-10-10T19:10:59Z",
"description": "\u003cb\u003eanother one\u003c/b\u003e",
"refundableStatus": "FULLY_REFUNDABLE"
}
],
"penaltyDescription": "dummy penalty description"
},
"guarantee": {
"acceptedPayments": [
"VISA"
],
"guaranteeType": "DEPOSIT_REQUIRED"
},
"nightlyPrices": [
{
"basePrice": 90,
"currencyCode": "USD",
"endDate": "2024-05-01",
"fees": {
"amount": 0
},
"startDate": "2024-04-30",
"taxes": {
"amount": 10,
"taxBreakdown": [
{
"amount": 6,
"fttCode": 33,
"inclusive": true
},
{
"amount": 4,
"fttCode": 44,
"inclusive": true
}
]
},
"totalPrice": 120
},
{
"basePrice": 10,
"currencyCode": "EUR",
"endDate": "2024-05-02",
"fees": {
"amount": 20,
"feeBreakdown": [
{
"amount": 6,
"fttCode": 33,
"inclusive": true
},
{
"amount": 4,
"fttCode": 44,
"inclusive": true
}
]
},
"startDate": "2024-05-01",
"taxes": {
"amount": 0
},
"totalPrice": 60
}
],
"prepayRequired": true,
"rateCategory": "AAA",
"rateDescription": [
"dummy rate description 0",
"dummy rate description 1"
],
"ratePlanId": "dummy rate plan id",
"refundable": true,
"roomId": "dummy room id",
"totalPrice": {
"currencyCode": "USD",
"fees": 10,
"taxes": 20,
"totalAfterTax": 130,
"totalBeforeTax": 100
}
},
"status": "RESERVED"
}
]
}
Update booking on existing trip.
{
"changeId": "00000000-0000-0000-0000-000000000000",
"changeTimestamp": "2024-04-30T12:26:16-05:00",
"changeTypeCode": "UPDATE",
"oldBooking": {
"bookingId": "00000000-0000-0000-0000-000000000000",
"confirmationCodes": null,
"status": "PENDING_CONFIRMATION"
},
"updatedBookings": [
{
"bookingId": "00000000-0000-0000-0000-000000000000",
"confirmationCodes": null,
"roomDescription": [
"updated room description"
],
"status": "RESERVED"
}
]
}
Replace booking on existing trip.
{
"changeId": "00000000-0000-0000-0000-000000000000",
"changeTimestamp": "2024-04-30T12:26:19-05:00",
"changeTypeCode": "REPLACE",
"oldBooking": {
"bookingId": "00000000-0000-0000-0000-000000000000",
"confirmationCodes": [
{
"code": "000000-TEST",
"codeType": "CANCELLATION"
}
],
"status": "CANCELLED"
},
"updatedBookings": [
{
"basicHotelProperty": {
"address": {
"addressLines": [
"line 1",
"line 2"
],
"city": "dummy city",
"countryCode": "dummy country code",
"postalCode": "dummy postal code",
"state": "dummy state",
"stateName": "dummy state name"
},
"chainCode": "dummy chain code",
"cityCode": "dummy city code",
"contactInfo": {
"emails": [
"someone@somewhere.com"
],
"faxNumber": "456",
"phoneNumbers": [
"123",
"890"
]
},
"hotelName": "dummy hotel name",
"position": {
"latitude": 2,
"longitude": 3
},
"propertyCode": "dummy property code"
},
"checkin": "2024-04-30",
"checkout": "2024-05-03",
"confirmationCodes": [
{
"code": "dummy supplier confirmation code",
"codeType": "SUPPLIER_CONFIRMATION"
}
],
"guests": [
{
"address": {
"addressLines": [
"123 Green St",
""
],
"city": "Albuquerque",
"countryCode": "US",
"postalCode": "87104",
"state": "New Mexico"
},
"birthdate": "1959-09-07",
"companyName": "Best Company Ever",
"contactInfo": {
"emails": [
"w@w.com"
],
"faxNumber": "456",
"phoneNumbers": [
"123"
]
},
"firstname": "John",
"lastname": "Smith"
}
],
"isModifiable": true,
"roomRate": {
"cancelPenalties": {
"penalties": [
{
"amountPercent": {
"amount": {
"amount": 100,
"currencyCode": "USD"
},
"applyAs": "FIRST_AND_LAST_NIGHT_DEPOSIT",
"basisType": "FULL_STAY",
"feesInclusive": true,
"numberOfNights": 3,
"percent": 99,
"taxInclusive": true
},
"cancelDeadline": "2018-10-10T19:10:59Z",
"description": "<b>dummy description</b>",
"refundableStatus": "FULLY_REFUNDABLE"
},
{
"cancelDeadline": "2018-10-10T19:10:59Z",
"description": "<b>another one</b>",
"refundableStatus": "FULLY_REFUNDABLE"
}
],
"penaltyDescription": "dummy penalty description"
},
"guarantee": {
"acceptedPayments": [
"VISA"
],
"guaranteeType": "DEPOSIT_REQUIRED"
},
"nightlyPrices": [
{
"basePrice": 90,
"currencyCode": "USD",
"endDate": "2024-05-01",
"fees": {
"amount": 0
},
"startDate": "2024-04-30",
"taxes": {
"amount": 10,
"taxBreakdown": [
{
"amount": 6,
"fttCode": 33,
"inclusive": true
},
{
"amount": 4,
"fttCode": 44,
"inclusive": true
}
]
},
"totalPrice": 120
},
{
"basePrice": 10,
"currencyCode": "EUR",
"endDate": "2024-05-02",
"fees": {
"amount": 20,
"feeBreakdown": [
{
"amount": 6,
"fttCode": 33,
"inclusive": true
},
{
"amount": 4,
"fttCode": 44,
"inclusive": true
}
]
},
"startDate": "2024-05-01",
"taxes": {
"amount": 0
},
"totalPrice": 60
}
],
"prepayRequired": true,
"rateCategory": "AAA",
"rateDescription": [
"dummy rate description 0",
"dummy rate description 1"
],
"ratePlanId": "dummy rate plan id",
"refundable": true,
"roomId": "dummy room id",
"totalPrice": {
"currencyCode": "USD",
"fees": 10,
"taxes": 20,
"totalAfterTax": 130,
"totalBeforeTax": 100
}
},
"status": "RESERVED"
},
{
"basicHotelProperty": {
"address": {
"addressLines": [
"line 1",
"line 2"
],
"city": "dummy city",
"countryCode": "dummy country code",
"postalCode": "dummy postal code",
"state": "dummy state",
"stateName": "dummy state name"
},
"chainCode": "dummy chain code",
"cityCode": "dummy city code",
"contactInfo": {
"emails": [
"sasha@sap.com"
],
"faxNumber": "456",
"phoneNumbers": [
"123",
"890"
]
},
"hotelName": "dummy hotel name",
"position": {
"latitude": 2,
"longitude": 3
},
"propertyCode": "dummy property code"
},
"checkin": "2024-04-30",
"checkout": "2024-05-03",
"confirmationCodes": [
{
"code": "dummy supplier confirmation code",
"codeType": "SUPPLIER_CONFIRMATION"
}
],
"guests": [
{
"address": {
"addressLines": [
"123 Green St",
""
],
"city": "Albuquerque",
"countryCode": "US",
"postalCode": "87104",
"state": "New Mexico"
},
"birthdate": "1959-09-07",
"companyName": "Best Company Ever",
"contactInfo": {
"emails": [
"w@w.com"
],
"faxNumber": "456",
"phoneNumbers": [
"123"
]
},
"firstname": "John",
"lastname": "Smith"
}
],
"isModifiable": true,
"roomRate": {
"cancelPenalties": {
"penalties": [
{
"amountPercent": {
"amount": {
"amount": 100,
"currencyCode": "USD"
},
"applyAs": "FIRST_AND_LAST_NIGHT_DEPOSIT",
"basisType": "FULL_STAY",
"feesInclusive": true,
"numberOfNights": 3,
"percent": 99,
"taxInclusive": true
},
"cancelDeadline": "2018-10-10T19:10:59Z",
"description": "<b>dummy description</b>",
"refundableStatus": "FULLY_REFUNDABLE"
},
{
"cancelDeadline": "2018-10-10T19:10:59Z",
"description": "<b>another one</b>",
"refundableStatus": "FULLY_REFUNDABLE"
}
],
"penaltyDescription": "dummy penalty description"
},
"guarantee": {
"acceptedPayments": [
"VISA"
],
"guaranteeType": "DEPOSIT_REQUIRED"
},
"nightlyPrices": [
{
"basePrice": 90,
"currencyCode": "USD",
"endDate": "2024-05-01",
"fees": {
"amount": 0
},
"startDate": "2024-04-30",
"taxes": {
"amount": 10,
"taxBreakdown": [
{
"amount": 6,
"fttCode": 33,
"inclusive": true
},
{
"amount": 4,
"fttCode": 44,
"inclusive": true
}
]
},
"totalPrice": 120
},
{
"basePrice": 10,
"currencyCode": "EUR",
"endDate": "2024-05-02",
"fees": {
"amount": 20,
"feeBreakdown": [
{
"amount": 6,
"fttCode": 33,
"inclusive": true
},
{
"amount": 4,
"fttCode": 44,
"inclusive": true
}
]
},
"startDate": "2024-05-01",
"taxes": {
"amount": 0
},
"totalPrice": 60
}
],
"prepayRequired": true,
"rateCategory": "AAA",
"rateDescription": [
"dummy rate description 0",
"dummy rate description 1"
],
"ratePlanId": "dummy rate plan id",
"refundable": true,
"roomId": "dummy room id",
"totalPrice": {
"currencyCode": "USD",
"fees": 10,
"taxes": 20,
"totalAfterTax": 130,
"totalBeforeTax": 100
}
},
"status": "RESERVED"
}
]
}
Cancel booking on existing trip.</summary>
{
"changeId": "00000000-0000-0000-0000-000000000000",
"changeTimestamp": "2024-04-30T12:26:17-05:00",
"changeTypeCode": "CANCEL",
"oldBooking": {
"bookingId": "00000000-0000-0000-0000-000000000000",
"confirmationCodes": [
{
"code": "123456",
"codeType": "CANCELLATION"
}
],
"status": "CANCELLED"
}
}
Replace booking on existing trip.
{
"changeId": "00000000-0000-0000-0000-000000000000",
"changeTimestamp": "2024-04-30T12:26:19-05:00",
"changeTypeCode": "REPLACE",
"oldBooking": {
"bookingId": "00000000-0000-0000-0000-000000000000",
"confirmationCodes": [
{
"code": "000000-TEST",
"codeType": "CANCELLATION"
}
],
"status": "CANCELLED"
},
"updatedBookings": [
{
"basicHotelProperty": {
"address": {
"addressLines": [
"line 1",
"line 2"
],
"city": "dummy city",
"countryCode": "dummy country code",
"postalCode": "dummy postal code",
"state": "dummy state",
"stateName": "dummy state name"
},
"chainCode": "dummy chain code",
"cityCode": "dummy city code",
"contactInfo": {
"emails": [
"someone@somewhere.com"
],
"faxNumber": "456",
"phoneNumbers": [
"123",
"890"
]
},
"hotelName": "dummy hotel name",
"position": {
"latitude": 2,
"longitude": 3
},
"propertyCode": "dummy property code"
},
"checkin": "2024-04-30",
"checkout": "2024-05-03",
"confirmationCodes": [
{
"code": "dummy supplier confirmation code",
"codeType": "SUPPLIER_CONFIRMATION"
}
],
"guests": [
{
"address": {
"addressLines": [
"123 Green St",
""
],
"city": "Albuquerque",
"countryCode": "US",
"postalCode": "87104",
"state": "New Mexico"
},
"birthdate": "1959-09-07",
"companyName": "Best Company Ever",
"contactInfo": {
"emails": [
"w@w.com"
],
"faxNumber": "456",
"phoneNumbers": [
"123"
]
},
"firstname": "John",
"lastname": "Smith"
}
],
"isModifiable": true,
"roomRate": {
"cancelPenalties": {
"penalties": [
{
"amountPercent": {
"amount": {
"amount": 100,
"currencyCode": "USD"
},
"applyAs": "FIRST_AND_LAST_NIGHT_DEPOSIT",
"basisType": "FULL_STAY",
"feesInclusive": true,
"numberOfNights": 3,
"percent": 99,
"taxInclusive": true
},
"cancelDeadline": "2018-10-10T19:10:59Z",
"description": "<b>dummy description</b>",
"refundableStatus": "FULLY_REFUNDABLE"
},
{
"cancelDeadline": "2018-10-10T19:10:59Z",
"description": "<b>another one</b>",
"refundableStatus": "FULLY_REFUNDABLE"
}
],
"penaltyDescription": "dummy penalty description"
},
"guarantee": {
"acceptedPayments": [
"VISA"
],
"guaranteeType": "DEPOSIT_REQUIRED"
},
"nightlyPrices": [
{
"basePrice": 90,
"currencyCode": "USD",
"endDate": "2024-05-01",
"fees": {
"amount": 0
},
"startDate": "2024-04-30",
"taxes": {
"amount": 10,
"taxBreakdown": [
{
"amount": 6,
"fttCode": 33,
"inclusive": true
},
{
"amount": 4,
"fttCode": 44,
"inclusive": true
}
]
},
"totalPrice": 120
},
{
"basePrice": 10,
"currencyCode": "EUR",
"endDate": "2024-05-02",
"fees": {
"amount": 20,
"feeBreakdown": [
{
"amount": 6,
"fttCode": 33,
"inclusive": true
},
{
"amount": 4,
"fttCode": 44,
"inclusive": true
}
]
},
"startDate": "2024-05-01",
"taxes": {
"amount": 0
},
"totalPrice": 60
}
],
"prepayRequired": true,
"rateCategory": "AAA",
"rateDescription": [
"dummy rate description 0",
"dummy rate description 1"
],
"ratePlanId": "dummy rate plan id",
"refundable": true,
"roomId": "dummy room id",
"totalPrice": {
"currencyCode": "USD",
"fees": 10,
"taxes": 20,
"totalAfterTax": 130,
"totalBeforeTax": 100
}
},
"status": "RESERVED"
},
{
"basicHotelProperty": {
"address": {
"addressLines": [
"line 1",
"line 2"
],
"city": "dummy city",
"countryCode": "dummy country code",
"postalCode": "dummy postal code",
"state": "dummy state",
"stateName": "dummy state name"
},
"chainCode": "dummy chain code",
"cityCode": "dummy city code",
"contactInfo": {
"emails": [
"sasha@sap.com"
],
"faxNumber": "456",
"phoneNumbers": [
"123",
"890"
]
},
"hotelName": "dummy hotel name",
"position": {
"latitude": 2,
"longitude": 3
},
"propertyCode": "dummy property code"
},
"checkin": "2024-04-30",
"checkout": "2024-05-03",
"confirmationCodes": [
{
"code": "dummy supplier confirmation code",
"codeType": "SUPPLIER_CONFIRMATION"
}
],
"guests": [
{
"address": {
"addressLines": [
"123 Green St",
""
],
"city": "Albuquerque",
"countryCode": "US",
"postalCode": "87104",
"state": "New Mexico"
},
"birthdate": "1959-09-07",
"companyName": "Best Company Ever",
"contactInfo": {
"emails": [
"w@w.com"
],
"faxNumber": "456",
"phoneNumbers": [
"123"
]
},
"firstname": "John",
"lastname": "Smith"
}
],
"isModifiable": true,
"roomRate": {
"cancelPenalties": {
"penalties": [
{
"amountPercent": {
"amount": {
"amount": 100,
"currencyCode": "USD"
},
"applyAs": "FIRST_AND_LAST_NIGHT_DEPOSIT",
"basisType": "FULL_STAY",
"feesInclusive": true,
"numberOfNights": 3,
"percent": 99,
"taxInclusive": true
},
"cancelDeadline": "2018-10-10T19:10:59Z",
"description": "<b>dummy description</b>",
"refundableStatus": "FULLY_REFUNDABLE"
},
{
"cancelDeadline": "2018-10-10T19:10:59Z",
"description": "<b>another one</b>",
"refundableStatus": "FULLY_REFUNDABLE"
}
],
"penaltyDescription": "dummy penalty description"
},
"guarantee": {
"acceptedPayments": [
"VISA"
],
"guaranteeType": "DEPOSIT_REQUIRED"
},
"nightlyPrices": [
{
"basePrice": 90,
"currencyCode": "USD",
"endDate": "2024-05-01",
"fees": {
"amount": 0
},
"startDate": "2024-04-30",
"taxes": {
"amount": 10,
"taxBreakdown": [
{
"amount": 6,
"fttCode": 33,
"inclusive": true
},
{
"amount": 4,
"fttCode": 44,
"inclusive": true
}
]
},
"totalPrice": 120
},
{
"basePrice": 10,
"currencyCode": "EUR",
"endDate": "2024-05-02",
"fees": {
"amount": 20,
"feeBreakdown": [
{
"amount": 6,
"fttCode": 33,
"inclusive": true
},
{
"amount": 4,
"fttCode": 44,
"inclusive": true
}
]
},
"startDate": "2024-05-01",
"taxes": {
"amount": 0
},
"totalPrice": 60
}
],
"prepayRequired": true,
"rateCategory": "AAA",
"rateDescription": [
"dummy rate description 0",
"dummy rate description 1"
],
"ratePlanId": "dummy rate plan id",
"refundable": true,
"roomId": "dummy room id",
"totalPrice": {
"currencyCode": "USD",
"fees": 10,
"taxes": 20,
"totalAfterTax": 130,
"totalBeforeTax": 100
}
},
"status": "RESERVED"
}
]
}