Lodging PreCancel Booking API

Guidance and examples for accessing the Lodging PreCancel Booking API

The Lodging PreCancel Booking API allows you to check whether an itinerary can be canceled via the API, what penalties might apply, and the timelines associated with those. It requires data that is only available at time of booking, so you can only cancel trips that you have booked.

Endpoint

Method	Endpoint	Prerequisites
GET	https://apim.expedia.com/hotels/bookings/[TripNumber]/canceldetails	An active TripNumber from the Lodging Booking API.

Required Headers

Key:	Expedia API key
Authorization:	Expedia API Authorization String
User-Id:	username@domain.com The email address associated with the booking.
Accept:	application/ vnd.exp-hotel.v3+json
Partner-Transaction-Id:	[Partner TransactionID String]

Next Steps

Cancel a booking via Lodging Cancel API.
Hotel to confirm if we return retrieve api link.

Example PreCancel Request

PreCancel Request

https://apim.expedia.com/hotels/bookings/12345/canceldetails

PreCancel Response

{
	"TransactionId": "fe2d94ae-7b9a-4f8c-aa80-8484b75da260",
	"ItineraryNumber": 7161340691,
	"PartnerConfirmationNumber": "hello123",
	"PartnerAgentId": "123456",
	"Status": "BOOKED",
	"TotalPrice": {
		"Value": "440.12",
		"Currency": "USD"
	},
	"TotalPenalty": {
		"Value": "0.00",
		"Currency": "USD"
	},
	"TotalOutstandingRefund": {
		"Value": "440.12",
		"Currency": "USD"
	},
	"CancellationDetails": [{
		"RoomConfirmation": "7af0f22c-eefe-4c06-bc6c-ccb68dba9574",
		"Penalty": {
			"Value": "0.00",
			"Currency": "USD"
		},
		"Refund": {
			"Value": "440.12",
			"Currency": "USD",
			"Type": "Full"
		},
		"Status": "BOOKED",
		"CancellationPolicy": {
			"Refundable": true,
			"FreeCancellation": true,
			"FreeCancellationEndDateTime": "2022-09-26T19:00:00-07:00",
			"CancellationPenaltyRules": [{
					"PenaltyNightCount": 1,
					"PenaltyStartDateTime": "2022-09-26T19:00:00-07:00",
					"penaltyEndDateTime": "2022-09-27T19:00:00-07:00"
				},
				{
					"PenaltyPercentOfStay": 100,
					"PenaltyStartDateTime": "2022-09-27T19:00:00-07:00",
					"penaltyEndDateTime": "2022-09-28T19:00:00-07:00"
				}
			]
			"CancelPolicyDescription": "There is no charge for cancellations made before 23:59 (property local time) on January 13, 2024.Cancellations or changes made after 23:59 (property local time) on January 13, 2024 or no-shows are subject to a property fee equal to the first nights rate plus taxes and fees."
		},
		"Links": {
			"ApiCancel": {
				"Accept": "application/vnd.exp-hotel.v3+json",
				"Method": "PUT",
				"Href": "https://esfvmvi-2709:8443/hotels/bookings/7161340691?roomConfirmations=7af0f22c-eefe-4c06-bc6c-ccb68dba9574"
			}
		}
	}],
	"Links": {
		"ApiCancel": {
			"Accept": "application/vnd.exp-hotel.v3+json",
			"Method": "PUT",
			"Href": "https://esfvmvi-2709:8443/hotels/bookings/7161340691"
		},
		"WebItinRetrieve": {
			"Href": "https://www.expedia.com/trips/7161340691?userToken=NA5njXYmi7BqaJe1XTDK1Iu520E9jxyCRY6eeIXsUdd8OHgvGQFzjcMvcvlU6slpaWamhKrZeouyEiSzuiywv5ryPvI5l6B5GZhz"
		},
		"ApiItinRetrieve": {
			"Accept": "application/vnd.exp-hotel.v3+json",
			"Method": "GET",
			"Href": "https://esfvmvi-2709:8443/hotels/bookings/7161340691"
		}
	}
}

Hotel Book PreCancel Sample Response - With Coupon

{
	"TransactionId": "a55b207b-0a2b-4386-a4ff-61c143568fa9",
	"ItineraryNumber": 790008033721,
	"PartnerConfirmationNumber": "hello123",
	"PartnerAgentId": "123456",
	"Status": "BOOKED",
	"TotalPrice": {
		"Value": "398.99",
		"Currency": "GBP"
	},
	"TotalPenalty": {
		"Value": "0.00",
		"Currency": "GBP"
	},
	"TotalOutstandingRefund": {
		"Value": "398.99",
		"Currency": "GBP"
	},
	"CancellationDetails": [{
		"RoomConfirmation": "f8521351-ad2b-4f41-a426-a04a40310d69",
		"Refund": {
			"Value": "398.99",
			"Currency": "GBP",
			"Type": "Full"
		},
		"Penalty": {
			"Value": "0.00",
			"Currency": "GBP"
		},
		"Status": "BOOKED",
		"CancellationPolicy": {
			"Refundable": true,
			"FreeCancellation": true,
			"FreeCancellationEndDateTime": "2022-09-27T19:59:00+00:00",
			"CancellationPenaltyRules": [{
					"PenaltyNightCount": 1,
					"PenaltyStartDateTime": "2022-09-27T19:59:00+00:00",
					"PenaltyEndDateTime": "2022-09-02T19:59:00+00:00"
				},
				{
					"PenaltyPercentOfStay": "100",
					"PenaltyStartDateTime": "2022-09-02T19:59:00+00:00",
					"PenaltyEndDateTime": "2022-09-05T19:59:00+00:00"
				}
			]
		},
		"Links": {
			"ApiCancel": {
				"Accept": "application/vnd.exp-hotel.v3+json",
				"Method": "PUT",
				"Href": "https://apim.expedia.com/hotels/bookings/790008033721?roomConfirmations=f8521351-ad2b-4f41-a426-a04a40310d69"
			}
		}
	}],
	"Links": {
		"ApiCancel": {
			"Accept": "application/vnd.exp-hotel.v3+json",
			"Method": "PUT",
			"Href": "https://apim.expedia.com/hotels/bookings/790008033721"
		},
		"WebItinRetrieve": {
			"Href": "https://www.expedia.com/trips/790008033721?userToken=TT5ec2LiNzEinB3hVGeM4VuWEbXs1B6BVCcWi-NZeNa4tapdn76s0c1mERKT0llUC0tOFqGrR5X8dfSbLZJ8tM3krTm-g8QZQ-gy"
		},
		"ApiItinRetrieve": {
			"Accept": "application/vnd.exp-hotel.v3+json",
			"Method": "GET",
			"Href": "https://apim.expedia.com/hotels/bookings/790008033721"
		}
	},
	"AppliedCoupon": {
		"Code": "EwsTestUKS13",
		"Discount": {
			"Value": "13.00",
			"Currency": "GBP"
		}
	}
}

Hotel Book PreCancel Sample Response - with Prices Returned in Hotel Local Currency

{
	"TransactionId": "c615a062-8bd1-4513-81f4-9eb1626df1c4",
	"ItineraryNumber": 790520968636,
	"PartnerConfirmationNumber": "hello123",
	"PartnerAgentId": "123456",
	"Status": "BOOKED",
	"TotalPrice": {
		"Value": "49109.10",
		"Currency": "JPY"
	},
	"TotalPriceInHotelLocalCurrency": {
		"Value": "10308375.00",
		"Currency": "VND"
	},
	"TotalPenalty": {
		"Value": "16369.70",
		"Currency": "JPY"
	},
	"TotalPenaltyInHotelLocalCurrency": {
		"Value": "3436125.00",
		"Currency": "VND"
	},
	"TotalOutstandingRefund": {
		"Value": "32739.40",
		"Currency": "JPY"
	},
	"TotalOutstandingRefundInHotelLocalCurrency": {
		"Value": "6872250.00",
		"Currency": "VND"
	},
	"CancellationDetails": [{
		"RoomConfirmation": "d64739d1-e020-4e64-aad6-acb70b5d91d4",
		"Refund": {
			"Value": "32739.40",
			"Currency": "JPY",
			"Type": "Partial"
		},
		"RefundInHotelLocalCurrency": {
			"Value": "6872250.00",
			"Currency": "VND",
			"Type": "Partial"
		},
		"Penalty": {
			"Value": "16369.70",
			"Currency": "JPY"
		},
		"PenaltyInHotelLocalCurrency": {
			"Value": "3436125.00",
			"Currency": "VND"
		},
		"Status": "BOOKED",
		"CancellationPolicy": {
			"Refundable": true,
			"FreeCancellation": false,
			"CancellationPenaltyRules": [{
					"PenaltyNightCount": 1,
					"PenaltyStartDateTime": "2022-08-28T18:00:00+00:00",
					"PenaltyEndDateTime": "2022-10-09T09:00:00+00:00"
				},
				{
					"PenaltyPercentOfStay": "100",
					"PenaltyStartDateTime": "2022-10-09T09:00:00+00:00",
					"PenaltyEndDateTime": "2022-10-12T09:00:00+00:00"
				}
			]
		},
		"Links": {
			"ApiCancel": {
				"Accept": "application/vnd.exp-hotel.v3+json",
				"Method": "PUT",
				"Href": "https://apim.expedia.com/hotels/bookings/790520968636?roomConfirmations=d64739d1-e020-4e64-aad6-acb70b5d91d4"
			}
		}
	}],
	"Links": {
		"ApiCancel": {
			"Accept": "application/vnd.exp-hotel.v3+json",
			"Method": "PUT",
			"Href": "https://apim.expedia.com/hotels/bookings/790520968636"
		},
		"WebItinRetrieve": {
			"Href": "https://www.expedia.co.jp/trips/790520968636?userToken=QfIey-8Z8-PlpGNCphHKHJn_dgONXwTeCTntZ33Y_U0g5YFC_H-yFeZKFGOd-ltpUq-RV34U7bFS-WCmQPtp7TDSEEtt0FRNI_nV"
		},
		"ApiItinRetrieve": {
			"Accept": "application/vnd.exp-hotel.v3+json",
			"Method": "GET",
			"Href": "https://apim.expedia.com/hotels/bookings/790520968636"
		}
	}
}

Hotel Book PreCancel Sample Response - With Some Booked Rooms Cancelled

{
	"TransactionId": "58c86679-7d9e-4018-9c98-3db3cf8c1cd6",
	"ItineraryNumber": 750430738197,
	"PartnerConfirmationNumber": "hello123",
	"PartnerAgentId": "123456",
	"Status": "BOOKED",
	"TotalPrice": {
		"Value": "781.41",
		"Currency": "AUD"
	},
	"TotalPenalty": {
		"Value": "781.41",
		"Currency": "AUD"
	},
	"TotalOutstandingRefund": {
		"Value": "0.00",
		"Currency": "AUD"
	},
	"CancellationDetails": [{
			"RoomConfirmation": "8a152236-d1a0-4c6d-895d-acd306d98b92",
			"Refund": {
				"Value": "0.00",
				"Currency": "AUD",
				"Type": "None"
			},
			"Penalty": {
				"Value": "781.41",
				"Currency": "AUD"
			},
			"Status": "BOOKED",
			"CancellationPolicy": {
				"Refundable": false,
				"FreeCancellation": false,
				"CancellationPenaltyRules": [{
					"PenaltyPercentOfStay": "100",
					"PenaltyStartDateTime": "2022-10-18T22:12:00-05:00",
					"PenaltyEndDateTime": "2022-09-05T19:00:00-05:00"
				}],
				"CancelPolicyDescription": "This reservation is non-refundable and cannot be cancelled or changed.",
				"NonRefundableDateRanges": [{
						"StartDate": "2022-09-05",
						"EndDate": "2022-09-05"
					},
					{
						"StartDate": "2022-09-06",
						"EndDate": "2022-09-06"
					},
					{
						"StartDate": "2022-09-07",
						"EndDate": "2022-09-07"
					}
				]
			},
			"Links": {
				"ApiCancel": {
					"Accept": "application/vnd.exp-hotel.v3+json",
					"Method": "PUT",
					"Href": "https://ews-booking-service.us-west-2.test.expedia.com/hotels/bookings/750430738197?roomConfirmations=8a152236-d1a0-4c6d-895d-acd306d98b92"
				}
			}
		},
		{
			"RoomConfirmation": "db2054a8-cc74-4c77-b8eb-1a713ca7b1e8",
			"Status": "CANCELED"
		}
	],
	"Links": {
		"ApiCancel": {
			"Accept": "application/vnd.exp-hotel.v3+json",
			"Method": "PUT",
			"Href": "https://ews-booking-service.us-west-2.test.expedia.com/hotels/bookings/750430738197"
		},
		"WebItinRetrieve": {
			"Href": "https://wwwexpediacomau.integration.sb.karmalab.net/trips/750430738197?userToken=Fm1N-qP2lMpmqi3YwUWuucg1uFay5UL1XnDmTVct0DsI1q7HR9X6-sA5L33HsOzBpdoj1-eXpKcbTQtF4uQ8Sec-T8-vr6wT99u1"
		},
		"ApiItinRetrieve": {
			"Accept": "application/vnd.exp-hotel.v3+json",
			"Method": "GET",
			"Href": "https://ews-booking-service.us-west-2.test.expedia.com/hotels/bookings/750430738197"
		}
	}
}

Error Codes

Common Error Codes

HTTPStatusCode	Error Code	Error Response	Cause
400	UNKNOWN_PATH	Unknown request path	Your request is not recognized as a valid API request URL.
400	INVALID_ACCEPT_HEADER	API version is either missing or invalid. Please provide a correct API version in the Accept header.	Your Accept Header is not correctly formatted.
400	PARTNER_TRANSACTION_ID_MISSING	Partner Transaction Id in http headers is missing.	You did not include the Partner-Transaction-Id value in your query header.
400	INVALID_CLIENT_KEY	Invalid client key:XXX.	Your client key is not authorized to access this API.
400	INVALID_USER_ID	The email address is either missing or invalid.	The email address that you have provided is not present, not a valid email address, or not associated to any active itineraries.
400	INVALID_ITINERARY_NUMBER	The itinerary number is either missing or invalid. Itinerary Number : xxxxxxxxx.	The itinerary number given is in an invalid format or value.
400	ITINERARY_NOT_FOUND	The itinerary was not found. Please provide valid user-id and itinerary number.	The trip number used does not exist for the given user-id.
400	BOOKING_ALREADY_CANCELLED	The booking was already canceled.	The Itinerary was already cancelled.
400	PRE_CANCEL_BOOKING_NOT_FOUND	The trip is not booked.	There is no booked trip that matches that itinerary.
400	ITINERARY_NOT_FOUND_FOR_PARTNER	Itinerary %s was not found for client key %s.	The itinerary does not belog to the partner.
400	ITIN_NOT_ASSOCIATED_WITH_CLIENT_KEY	The itinerary %s is not associated with client key %s.	The itinerary belongs to a different POS.
500	RETRIEVE_ITINERARY_ERROR	Unable to retrieve data for itinerary number s%. Please try again later.	There was an unknown error.
500	PRE_CANCEL_APPLICATION_ERROR	Pre-Cancellation failed. Application Error.	There was an unknown error.
500	PRE_CANCEL_BOOKING_ITIN_EXPIRED	Pre-Cancellation failed. The itinerary date is in the past.	The trip is no longer in the future, so the trip cannot be cancelled because it is in the past.
400	INVALID_USER_CREDENTIALS	User credentials are either missing or invalid.	User info authentication failed.
500	PRE_CANCEL_CANNOT_ON_LINE	Pre-Cancellation failed. Cannot cancel hotel online.	This hotel not support online cancellation.
500	PRE_CANCEL_PENALTY_EXCEED_SELL_PRICE	Pre-Cancellation failed. Cancel-Penalty exceed the sell price.	Penalty calculation error.
500	PRE_CANCEL_ERROR_DUE_TO_CANCELATION_POLICY	Pre-Cancellation failed. Unable to cancel hotel due to hotel cancellation policy.	Unable to cancel hotel due to hotel cancellation policy.
500	PRE_CANCEL_ROLLBACK_SCHEDULED_PAYMENT_FAILED	Pre-Cancellation failed. Failed to cancel or rollback scheduled payments during a hotel cancellation.	Get cancel details is being processed. Please try again later.
500	PRE_CANCEL_HOTEL_RESERVATION_CONFIRM_FAILED	Pre-Cancellation failed. Hotel reservation cannot be confirmed. Please try again later.	There was an unknown error.
500	PRE_CANCEL_HOTEL_RESERVATION_CANNOT_BE_CANCELED	Pre-Cancellation failed. Hotel reservation cannot be cancelled. Cancellation made during cancellation window.	There was an unknown error.
500	INVALID_PRE_CANCEL_HOTEL_RESERVATION_STATE	Pre-Cancellation failed. The booking is currently being processed. Please try again later.	Get cancel details is being processed. Please try again later.

API details

Here, you can explore the endpoint definitions for this API, then go to the API Explorer to try out all the XAP endpoints, download OpenAPI specs, or download our Postman collections. Testing with one or all of these options will give you an understanding of how the examples and schema definitions compare to the actual output.