Modify your orders

Learn how to use the /orders/modify endpoint to update certain details in accommodation orders. This guide outlines supported use cases, required parameters, and practical examples to ensure successful modifications.

Overview

Use the orders/modify endpoint to update specific details within an existing accommodation reservation.

You can use this endpoint to update the following elements:

✅ Credit card details.
✅ Checkin and checkout dates.
✅ Room-level details (guest allocation, guest names, and smoking preferences).

Supported modifications by payment timing:

Endpoint usage

When making a request to the orders/modify endpoint, you must include:

Request body

The request body always includes:

Modifying card details

To change the payment method for a reservation:

1. Use the modification.payment object.
2. Set type to "card".
3. Include the following fields in the "change" object:

• number: The new credit card number.
• cvc: The card’s CVC code (3–4 digits).
• cardholder: The cardholder's name.
• expiry_date: The card's expiry date in YYYY-MM format.

Example request - Card modification

{
  "order": "4334069995",
  "modification": {
    "payment": {
      "type": "card",
      "change": {
        "number": "4111111111111111",
        "cvc": "737",
        "cardholder": "Jon Snow",
        "expiry_date": "2030-03"
      }
    }
  }
}

Example response - Successful card modification

{
  "modifications": {
    "payment": {
      "status": "successful"
    }
  }
}

Modifying checkin/out dates

To modify the stay period for a reservation:

1. Use the modification.accommodation to modify the dates.
2. Include the reservation ID.
3. Set type to "dates".
4. Include the new dates in change(checkin and checkout) using YYYY-MM-DD format.

Example request - Dates modification

{
  "order": "4297204980",
  "modification": {
    "accommodation": {
      "reservation": "4297204980",
      "type": "dates",
      "change": {
        "checkin": "2026-10-20",
        "checkout": "2026-10-21"
      }
    }
  }
}

Example response - Successful dates modification

In the case of dates modification, the response includes the new price for the modified reservation.

{
  "data": {
    "modification": {
      "accommodation": {
        "new_price": 78.25,
        "status": "successful"
      }
    }
  },
  "request_id": "UmFuZG9tSVYkc2RlIyh9YV3CugMXEW9cxCXzj8lTlg8gbGIrozNJUJEQ1pFr+WkAk9uAy/KRmk5J3xi9Yw1h0Xy4jTiofhCe/XCmws8MfGEjI253Pagi+Q=="
}

Modifying room details

To update room-level details such as guest names, allocation, or smoking preferences:

1. Use the modification.accommodation.
2. Set type to room.
3. Include the reservation ID.
4. In the change object, specify:

• room_reservation ID (string).
• guests.name - Update the guest name.
• allocation.number_of_adults - update number of adults.
• smoking_preference - Modify the smoking preference for the room ("smoking", "non_smoking", or "no_preference").

Example request - Room modification

{
  "order": "5000375899",
  "modification": {
    "accommodation": {
      "reservation": "5000375899",
      "type": "room",
      "change": {
        "room_reservation": "5448643068",
        "allocation": {
          "number_of_adults": 2
        },
        "guests": [
          { "name": "Test Test" },
          { "name": "Test2 Test" }
        ],
        "smoking_preference": "smoking"
      }
    }
  }
}

Example response - Successful room modification

{
  "data": {
    "modification": {
      "accommodation": {
        "status": "successful"
      }
    }
  },
  "request_id": "UmFuZG9tSVYkc2RlIyh9YUdRpaDGn9Pw2aEu"
}

Important considerations

• Separate requests per modification type - Room, card, and date updates must be done in separate requests. Ensure you only modify one aspect at a time.
• Room-level updates - These apply to individual room reservations, not the entire booking.
• Wait time - Allow at least 5 minutes between modification requests to the same order to prevent conflicts.
• No further action required - Once a modification succeeds, the system automatically updates the booking.

Price adjustments

Modifying dates or room occupancy may affect the price. To avoid unexpected costs:

1. Use the accommodations/availability endpoint to check availability and view updated pricing before modifying the reservation.
2. If the price is not acceptable, cancel and create a new order.

Error handling

Common errors include:

Card modification errors

Invalid card type

Returned when the property does not accept the card type provided in the modification request.

Example response:

{
  "errors": [
    {
      "id": "incorrect_parameters",
      "message": "Hotel does not accept card type {card_type}"
    }
  ]
}

Solution:

• Retrieve accepted card types from the methods.cards array returned by the /orders/preview endpoint.
• Update your request to include a supported card type.

Reservation-related errors

Reservation not found

This message is thrown when the specified reservation does not exist or cannot be located:

Example response:

{
  "errors": [
    {
      "id": "incorrect_parameters",
      "message": "Reservation not found"
    }
  ]
}

Solution:

• Retrieve reservation details using the /orders/details/accommodations endpoint
• Confirm that the reservation ID is correct and that the reservation is still active.

Modifying cancelled reservations

Returned when attempting to modify the dates of a reservation that has already been cancelled:

Example response:

{
  "errors": [
    {
      "id": "incorrect_parameters",
      "message": "Reservation is cancelled"
    }
  ]
}

Solution:

• Check the reservation status using the /orders/details/accommodations endpoint.
• If the reservation has been cancelled, it is not possible to change its dates.
• If you need to adjust dates, consider creating a new one.

Room modification errors

No valid change parameter specified

Returned when the request does not include any supported room-level fields.

Example response:

{
  "errors": [
    {
      "id": "incorrect_parameters",
      "message": "No valid change parameter specified"
    }
  ]
}

Solution:

• Ensure the change object includes at least one supported field:
  • room_reservation
  • allocation.number_of_adults
  • guests
  • smoking_preference

Room reservation not found

Returned when the specified room_reservation ID is invalid or does not belong to the order.

Example response:

{
  "errors": [
    {
      "id": "incorrect_parameters",
      "message": "Room reservation not found"
    }
  ]
}

Solution:

• Use the /orders/details/accommodations endpoint to verify:
  • That the room reservation ID provided is correct and corresponds to an active reservation.
  • The reservation has a "booked" status.

Guest number restriction

Returned when the rate is tied to a fixed number of guests and cannot be modified.

Example response:

{
  "errors": [
    {
      "id": "incorrect_parameters",
      "message": "Cannot change number of guests when rate-level occupancy is in effect"
    }
  ]
}

Solution:

• Cancel this order and create a new one with the desired guest count.

Guest number limit exceeded

Returned when the requested number of guests exceeds the room’s maximum occupancy.

Example response:

{
  "errors": [
    {
      "id": "incorrect_parameters",
      "message": "Number of guests exceeds the allowed limit for this room"
    }
  ]
}

Solution:

• Check the maximum occupancy for the room type using the accommodations/availability endpoint and adjust the number of guests to fall within that limit.
• If more guests are required, consider changing to a larger room type that can accommodate the additional number of people.

Invalid guest number

Returned when the guest number is zero or a negative value.

Example response:

{
  "errors": [
    {
      "id": "incorrect_parameters",
      "message": "Invalid number of guests specified"
    }
  ]
}

Solution:

• Ensure the number of guests is a positive integer within room limits.

Unchanged guest number

Returned when the requested guest number matches the existing value.

Example response:

{
  "errors": [
    {
      "id": "incorrect_parameters",
      "message": "Number of guests is already set to the requested value"
    }
  ]
}

Solution:

• Avoid submitting modification requests when no change is required.
• If a change is required, confirm that the requested guest number is different from the current number before submitting the request.

Smoking preference restriction

Returned when attempting to update the smoking preference for a room with a fixed smoking policy.

Example response:

{
  "errors": [
    {
      "id": "incorrect_parameters",
      "message": "Cannot change smoking preference; room is designated as '{smoking_type}' only"
    }
  ]
}

Solution:

1. Call the /orders/details endpoint with extras.room to retrieve room attributes.
2. Check whether the room is designated as smoking or non-smoking.
3. Select a different room if the preference cannot be changed.

Example of request:

{
  "accommodations": [
    10507360
  ],
  "extras": [
    "rooms"
  ],
  "languages": [
    "en-gb"
  ]
}

• The response will provide each room details including the room id and whether the room is smoking or not.

Example of response:

      "rooms": [
        {
          "id": 1050736001,
          "name": {
            "en-gb": "Single Room"
          },
          "attributes": [
            "non_smoking"
          ],
          "bed_options": [...]
                }
              ],

• If the room is designated as non-smoking, the preference field cannot be changed.
• Choose another room with the desired smoking status if required.

Invalid smoking preference

Returned when an unsupported or invalid smoking preference value is specified.

Example response:

{
  "errors": [
    {
      "id": "incorrect_parameters",
      "message": "Invalid smoking preference value: '{smoking}'"
    }
  ]
}

Solution:

• Check that the smoking preference is set to a valid value (e.g., "smoking" or "non-smoking") by using the /orders/details endpoint and passing the extras.room parameter in the request.

• If the request is for a specific room with a different smoking policy, adjust the preference accordingly or select another room that matches the desired smoking status.