POST /api/v1/hotels/cancel_hotel
Cancel a confirmed hotel booking owned by your agency. Requires Read+Write permission.
Cancel a confirmed hotel booking. Calls the supplier's cancellation API, then processes the refund against the cancellation policy that applied at booking time.
Permission: Read+Write
Only bookings currently in confirmed status can be cancelled through this endpoint. A booking
still pending (background confirmation in progress) or already cancelled/refunded returns
400 invalid_status.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
booking_id | string | Yes | The partner_order_id / bookingId from book_hotel |
Request example
curl --request POST \
--url https://api.fx-port.com/api/v1/hotels/cancel_hotel \
--header 'Authorization: Bearer fxp_test_YOUR_KEY' \
--header 'Content-Type: application/json' \
--data '{
"booking_id": "HMTLZLWGQ"
}'Response example
{
"environment": "sandbox",
"success": true,
"status": "ok",
"booking_id": "HMTLZLWGQ",
"refund_processed": true,
"agency_refund_amount": 43812.75,
"agency_currency": "DZD",
"refund": {
"cancellationType": "free_cancellation",
"type": "full",
"agencyAmount": 43812.75,
"travelerAmount": 43812.75,
"currency": "DZD",
"providerAmount": 291.00,
"providerCurrency": "EUR"
},
"webhookSent": true,
"processingTime": 1.532
}Field reference
| Field | Description |
|---|---|
refund.cancellationType | Which policy window applied — e.g. free_cancellation, partial_penalty, no_refund |
refund.agencyAmount | Amount credited back to your agency balance (agency currency) |
refund.providerAmount | The supplier-side penalty/refund amount (supplier currency, informational) |
webhookSent | Whether a cancellation webhook was delivered to your configured webhook URL |
Cancelling after the free-cancellation deadline still succeeds, but agencyAmount reflects
the penalty from cancellationPolicy.policies[] (see Rates & cancellation
policies) — it may be less than the full total_price, or
0 for a fully non-refundable rate.
In sandbox, cancelling does not touch a real balance (balanceDebited was already false at
booking time). See Sandbox testing for a note on supplier-side
sandbox housekeeping that can independently cancel/refund designated test-hotel bookings.