Cancel a confirmed hotel booking
Cancels a booking of your agency and refunds it according to the cancellation schedule of the rate.
/api/v1/hotels/cancel_hotelOnly a booking whose status is confirmed can be cancelled: right after book_hotel it is pending, so wait for confirmed. The booking becomes refunded (free cancellation), partial_refund (a penalty applied) or cancelled (nothing refunded). The call takes 1 to 4 seconds. The supplier occasionally takes 30 seconds and the call then fails with 503 supplier_timeout: the cancellation may or may not have happened, so read the booking, and call again only if it is still confirmed. In the sandbox cancel every test booking: it is free until 21:00 UTC on the check-in day.
curl https://api.fx-port.com/api/v1/hotels/cancel_hotel \
-H "Authorization: Bearer fxp_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"booking_id": "HMVXX4ZQ3"
}'{
"environment": "sandbox",
"success": true,
"status": "ok",
"bookingId": "HMVXX4ZQ3",
"bookingStatus": "refunded",
"adminCancel": false,
"refund": {
"cancellationType": "free",
"type": "Free cancellation",
"agencyAmount": 1482,
"travelerAmount": 1484.97,
"currency": "DZD",
"providerAmount": 3,
"providerCurrency": "EUR"
},
"refundProcessed": true,
"webhookSent": true,
"processingTime": 3.488
}Request
Body
Required, JSON.
booking_idstringrequiredThe id of the booking to cancel: the bookingId of book_hotel.
partner_order_idstringdeprecatedLegacy name, still accepted. Use booking_id instead.
The booking id, in its older spelling. Use booking_id.
partnerOrderIdstringdeprecatedLegacy name, still accepted. Use booking_id instead.
The booking id, in its older spelling. Use booking_id.
bookingIdstringdeprecatedLegacy name, still accepted. Use booking_id instead.
The booking id, in its older spelling. Use booking_id.
Response
200The booking is cancelled. bookingStatus and refund say what was given back.
environmentstringThe environment of the key that made the call: sandbox for fxp_test_ keys, live for fxp_live_ keys. Present in every JSON body.
One of sandbox, live.
request_idstringThe id of the request, also in the X-Request-Id header.
warningsarray of objectPresent only when the request used a previous spelling of a field or something the endpoint ignored.
ShowHide 5 attributes
codestringWhat the warning is about.
One of deprecated_field, ignored_field, coerced_value, deprecated_value, deprecated_endpoint.
fieldstringThe request field the warning is about.
replacementstringThe name to use instead, for deprecated_* warnings.
messagestringA sentence that says what happened and what to do.
documentation_urlstringWhere the naming rules are explained.
successbooleantrue when the supplier cancelled the booking.
statusstringAlways ok: the call worked. The state of the booking is bookingStatus.
Always ok.
bookingIdstringdeprecatedLegacy name, still accepted. Use booking_id instead.
The id of the booking that was cancelled.
booking_idstringThe id of the booking that was cancelled. The snake_case twin of bookingId, with the same value: use this name.
bookingStatusstringdeprecatedLegacy name, still accepted. Use booking_status instead.
The new status of the booking: refunded (free cancellation), partial_refund (a penalty applied) or cancelled (no refund).
One of refunded, partial_refund, cancelled.
booking_statusstringThe new status of the booking: refunded (free cancellation), partial_refund (a penalty applied) or cancelled (no refund). The snake_case twin of bookingStatus, with the same value: use this name.
One of refunded, partial_refund, cancelled.
adminCancelbooleantrue when FX-Port staff cancelled the booking. Always false for a call of yours.
refundobjectWhat the cancellation gave back.
ShowHide 13 attributes
cancellationTypestringdeprecatedLegacy name, still accepted. Use cancellation_type instead.
free: the supplier refunded everything; partial: a penalty applied; none: no refund.
One of free, partial, none.
cancellation_typestringfree: the supplier refunded everything; partial: a penalty applied; none: no refund. The snake_case twin of cancellationType, with the same value: use this name.
One of free, partial, none.
typestringThe same as a label for people.
One of Free cancellation, Partial cancellation, No refund.
agencyAmountnumberdeprecatedLegacy name, still accepted. Use agency_refund_amount instead.
What is credited back to your agency, in currency. 0 for none.
agency_refund_amountnumberWhat is credited back to your agency, in currency. 0 for none. The snake_case twin of agencyAmount, with the same value: use this name.
travelerAmountnumberdeprecatedLegacy name, still accepted. Use traveler_refund_amount instead.
What the traveler gets back, in currency.
traveler_refund_amountnumberWhat the traveler gets back, in currency. The snake_case twin of travelerAmount, with the same value: use this name.
currencystringdeprecatedLegacy name, still accepted. Use agency_currency instead.
The currency of your agency.
agency_currencystringThe currency of your agency. The snake_case twin of currency, with the same value: use this name.
providerAmountnumberdeprecatedLegacy name, still accepted. Use supplier_refund_amount instead.
What the supplier refunded, in providerCurrency.
supplier_refund_amountnumberWhat the supplier refunded, in providerCurrency. The snake_case twin of providerAmount, with the same value: use this name.
providerCurrencystringdeprecatedLegacy name, still accepted. Use supplier_currency instead.
The supplier's currency: EUR.
supplier_currencystringThe supplier's currency: EUR. The snake_case twin of providerCurrency, with the same value: use this name.
refundProcessedbooleandeprecatedLegacy name, still accepted. Use refund_processed instead.
true when the refund was handled. In the sandbox nothing moves, and the flag is still true.
refund_processedbooleantrue when the refund was handled. In the sandbox nothing moves, and the flag is still true. The snake_case twin of refundProcessed, with the same value: use this name.
webhookSentbooleanDescribes an internal step of FX-Port, not a message to you: FX-Port sends no webhooks to customers.
processingTimenumberdeprecatedLegacy name, still accepted. Use processing_time instead.
Seconds the call took.
processing_timenumberSeconds the call took. The snake_case twin of processingTime, with the same value: use this name.
Errors
| Status | Code | Example message |
|---|---|---|
| 400 | invalid_status | Booking is 'pending', can only cancel 'confirmed' bookings |
| 400 | missing_field | Missing required field: booking_id |
| 400 | invalid_booking_id | 'booking_id' must be 1 to 256 characters: letters, digits and '_ . : -' (got 'abc def'). |
| 403 | read_write_permission_required | This endpoint requires an API key with read_write permission. |
| 403 | forbidden | This booking does not belong to your agency. Only the agency that made the booking can cancel it. |
| 404 | booking_not_found | Booking HZZZZZZZZ not found |
| 502 | supplier_invalid_response | The hotel supplier returned an answer that could not be used. Retry in a few minutes. |
| 503 | supplier_timeout | The hotel supplier did not answer in time, so the request may or may not have been processed: read the booking's status before you retry. |
The shape of the error body depends on the endpoint. See Errors for every shape and code.