Handling cancellations

This guide outlines the steps necessary for a smooth cancellation experience, along with relevant examples.

The cancellation process

Cancellations can arise from various situations, including booking errors, or changes in travel plans. Therefore, it's crucial to familiarise yourself with the cancellation policies associated with each booking.

• Always consult the cancellation policies section before proceeding with a cancellation.

  Did you know?

  Cancellation policies are returned per-product rather than per-order. This allows you to easily manage complex multi-room bookings where different policies apply to different rooms.

• Make sure you understand the steps and recommendations provided in this guide to streamline your cancellation process.

Step-by-step process

1. Fetch the order/details

Upon receiving a cancellation request, verify first the order ID and retrieve relevant booking details using the /orders/details endpoint.

In your request, make sure you include the order ID (or reservation id).

{
  "orders": [
    "121312354"
  ],
  "currency": "EUR",
}

The response will retrieve the order information, including the payment method, price, status and when the order was last updated.

{
  "request_id": "01jrab3s38cr3k4wxmd6rsxx0m",
  "data": [
    {
      "id": "121312354",
      "accommodations": {
        "reservation": 121312354
      },
      "affiliate": 956509,
      "booker": {...},
      "cars": null,
      "created": "2025-02-04T10:24:59+00:00",
      "currency": "EUR",
      "flights": null,
      "payment": {
        "accommodations": {
          "authorization_form": "https://secure-admin.booking.com/airplus_auth_form_pdf.html?token=anNvbl9hbXM0Xzg0ZmIyNWZhLTdmODAtNGRlZC04NTAxLWFiMDVhYmZhN2Q0OQ%3D%3D&lang=en-us",
          "receipt_url": null,
          "reservation": 121312354
        },
        "method": "card",
        "paid": null,
        "pending": null,
        "timing": "pay_at_the_property"
      },
      "price": {
        "commissionable": 0,
        "total": 276.94
      },
      "status": "booked",
      "updated": "2025-02-04T10:25:00+00:00"
    }
  ],
  "metadata": {
    "next_page": null,
    "total_results": 1
  }
}

2. Verify the order status

Before cancelling, check the order status and last update.

In the example provided:

• The order has a booked status - therefore the order can be cancelled.
• And it was last updated on the "2025-02-04T10:25:00+00:00" (UTC time) when was created.

      },
      "status": "booked",
      "updated": "2025-02-04T10:25:00+00:00"
    }

The following statuses indicate that an order cannot be cancelled:

• "cancelled"
• "cancelled_by_accommodation"
• "cancelled_by_guest"
• "stayed"

Multi-room statuses

In cases where individual products have varying statuses, the "stayed" status takes precedence and is applied to both the accommodation and order status.

• For instance, if one room in the order is marked as "cancelled" while another is "stayed," the "stayed" status will be used for both the accommodation and the order.

3. Check the cancellation policy

Before proceeding, verify the booking's eligibility for cancellation according to its specific terms using the orders/details/accommodations endpoint, this way you can:

• Evaluate deadlines, potential fees, and any conditions that could impact the cancellation process.
• Help you communicate any penalties or refund policies to the traveller effectively.

The response will include whether there is cancellation fees. Example:

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": "121312354",
      "accommodation": 123456,
      "accommodation_details": {...},
      "accommodation_order_references": [
        "12345",
        "ABED2312"
      ],
      "booker": {...},
      "cancellation_details": {
        "at": "2025-03-02T00:00:00+00:00",
        "fee": {
          "accommodation_currency": 170.01,
          "booker_currency": 186.87
        }
      },
      "checkin": "2025-03-03",
      "checkout": "2025-03-08",
      "commission": {...}
      },
      "credit_slip": 1223445,
      "currency": {
        "accommodation": "EUR",
        "booker": "USD"
      },
      "key_collection_information": [...],
      "label": "One123",
      "pin_code": "1234",
      "price": {...},
      "products": [
        {
          "allocation": {...},
          "guests": [...],
          "policies": {
            "cancellation": [
              {
                "from": null,
                "price": {
                  "accommodation_currency": 170.01,
                  "booker_currency": 186.87
                }
              }
            ],
          "price": {
            "base": {
              "accommodation_currency": 170.01,
              "booker_currency": 186.87
            },
            "total": {
              "accommodation_currency": 200.97,
              "booker_currency": 220.9
            }
          },
          "room": 12345,
          "room_details": {...},
          "status": "booked"
        }
      ],
      "remarks": "We will need an extra cot. Need room on higher floor",
      "reservation": 123456,
      "status": "booked",
      "stay_probability": 0.12
    }
  ]
}

• The cancellation is free until 1 day before the checkin date (on the "2025-03-02T00:00:00+00:00")

• From 2025-03-02 (UCT time) the traveller will be charged the stated amount (186.87)

• At this point the order has not been cancelled yet, hence the status is "booked" and "cancellation.from" appears as "null".

4. Process the cancellation

If the order meets the cancellation criteria, call the cancellation order endpoint to proceed.

Required parameters

When making a cancellation request, include the following mandatory parameters:

Request example:

{
  "order": "509430129718799",
  "reason": "Change in trip plans."
}

Response status

When using the cancellation endpoint to cancel an order, you may receive the following response statuses:

• Successful
• Failed

Upon successful cancellation, the response will confirm the operation. Example:

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": {
    "status": "successful"
  }
}

If the cancellation fails it retrieves an error code and message. Check the handling errors section for more details.

5. Review and confirm in order details

After cancelling the order, wait up to 1 hour for the order to be updated.

Then use the orders/details/accommodations endpoint to verify the status value and the cancellation details again.

At this stage, the status should be "cancelled" and in the cancellation_details you will be able to check:

• The applied cancellation rules, including any fees and timelines.
• The cancellation fee with the amount that must be charged for the cancellation, according to the applicable cancellation policy.

In this example, the fee is 186.87 and must be paid at 2025-03-02T00:00:00+00:00:

{
  "cancellation_details": {
    "at": "2025-03-02T00:00:00+00:00",
    "fee": {
      "accommodation_currency": 170.01,
      "booker_currency": 186.87
    }
  }
}

6. Notify the traveller

After successfully cancelling the booking, send a confirmation notification to the traveller.

Include details about the cancellation and any applicable refunds. Example:

Always confirm the cancellation status with the guest to ensure they are informed.

Handling errors

If the cancellation is unsuccessful, the API returns an error message indicating the issue.

Common error responses may include:

Examples of error responses

400 error messages:

• If you attempt to cancel an order with a “stayed” status, you will receive this error message, indicating that checkout has already occurred:

{
  "request_id": "01jc0echvzdvwt4g1vc0yj280f",
  "errors": [
    {
      "id": "OrderNotCancellable",
      "message": "The order is no longer cancellable. Checkout was yyyy-mm-dd."
    }
  ]
}

• A similar message will appear if the order was already cancelled:

{
  "request_id": "01jc0echvzdvwt4g1vc0yj280f",
  "errors": [
    {
      "id": "OrderNotCancellable",
      "message": "The order has already been cancelled."
    }
  ]
}

Important considerations

• User initiation: Enable travellers to initiate the cancellation process through a user-friendly interface in your application.

  • Ensure they can easily access their booking information.
  • Keep the cancellation process simple and intuitive. Provide clear instructions and confirmation messages at each step.

• Cancellation policies: Be aware of the cancellation policies linked to the order, as these will dictate whether a cancellation fee applies or if cancellation is possible without penalties.

  • Clearly communicate cancellation policies during the booking process to reduce confusion and enhance trust.

• Time sensitivity: Some orders have specific time frames for cancellation.

  • Ensure you're acting within the allowed period to avoid complications.
  • Example: Cancellation cannot happen after checkin date.

• Testing and validation: Rigorously test the cancellation feature to ensure it functions as intended across various scenarios, including edge cases.