Retrieve the current order details via GET /orders/{orderId} to obtain the active cancellation policy object before initiating cancellation.
Parse the cancellation policy: check the cancel_penalties array for the active penalty window — each entry specifies a start_date, end_date, penalty_type (e.g., flat_fee, percentage, nights), and value.
If outside the free-cancellation window, calculate the expected penalty amount from the policy; surface this to the user and obtain confirmation before proceeding.
Submit DELETE /orders/{orderId}/cancel (or POST to the cancel endpoint per the API version) to cancel the booking; include any required reason code.
Parse the cancellation response: the response includes a cancellation_id, the penalty_amount charged, and the refund_amount to be returned to the original payment method.
Store the cancellation_id and refund details; monitor for the refund to appear in your payment gateway — Booking.com typically initiates refunds within a defined settlement window.
Known gotchas
Cancellation policies in the Demand API v3.2 renamed 'Special conditions' to 'Partially refundable' — if parsing policy type strings, update string comparisons to handle both values for backward compatibility.
Non-refundable rates return a penalty_amount equal to the full booking value; always re-confirm the rate type before initiating cancellation on behalf of a customer.
The cancellation_id returned by Booking.com is distinct from the original booking order ID — use the cancellation_id for all subsequent support queries about the cancellation.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp