Modify your orders

Learn how to use the /orders/modify endpoint to update certain details in accommodation orders

Overview

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

This functionality is available exclusively for accommodations offering "Pay at the property" timing and is not applicable to bookings that use online payment.

You can use this endpoint to update the following elements:

✅ Credit card details.

✅ Checkin and checkout dates.

✅ Room-level details (such as guest allocation, guest names, and smoking preferences)

This guide outlines supported use cases, required parameters, and practical examples to ensure successful modifications.

Endpoint usage

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

Required parameters

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, with the modified data:

• number: The new credit card number.
• cvc: The CVC number.
• cardholder: The cardholder's name.
• expiry_date: The card's expiry date in YYYY-MM format.

Example - Card modification request

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

Example - Successful card modification response

{
  "data": {
    "modifications": {
      "accommodation": {
        "payment": {
          "status": "successful",
          "type": "card"
        }
      }
    }
  },
  "request_id": "UmFuZG9tSVYkc2RlIyh9YbQc4ZyG3sK2XEgLts3EFBWpaHhlHm7cFsYT19mqggfkmKU6HHuwVMRyCl71JW2jeIIh8dGdptlhYLi7HudiT3wRlN+br65rDw=="
}

Modifying checkin/out dates

To modify the stay period for a reservation:

1. Use the modification.accommodation object to modify the dates.

2. Include the reservation id for identification.

3. Set type to "dates".

4. In the change object, include the new dates in YYYY-MM-DD format.

Example - Dates modification request

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

Example - 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 modify room details such as the guests allocation, names or the smoking preferences:

1. Use the accommodation object to modify the room reservation.

2. Set type to room.

3. Call the /orders/details/accommodation endpoint and copy the room_reservation id located under "products" in each object.

4. In the change object, specify:

• room_reservation id.
• guests.name - Update the guests names.
• allocation.number_of_adults - Modify the number of adults.
• smoking_preference - Modify the smoking preference for the room.

Example - Room details modification request

{
  "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 - 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.

• Final action - Once a modification request is successful, no further action is required.

Price adjustments

When modifying dates or room details, the price of the reservation may change. To avoid unexpected price differences:

1. Verify accommodation availability for the new dates or room details before making the modification request.

2. Use the accommodations/availability endpoint to check the updated price for the same property with the new requirements.

Error handling

When modifying an order, the API may return one or more errors if the request contains invalid or unsupported parameters.

Below is a list of common error scenarios, along with example responses.

Card modifications

Invalid card type

This error occurs when an attempt is made to update the payment method using a card type that is not accepted by the property.

Example response:

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

Solution:

• Ensure the card type you are using is supported by the accommodation. You can check the accepted card types in the methods.cards array returned by the /orders/preview endpoint.

• Update your request to include a supported card type.

Reservations

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:

Make a call to /orders/details/accommodations endpoint to:

• Double-check the reservation ID.

• Check the reservation status has not been cancelled or expired.

Modifying online payment orders

When attempting to modify an online payment order, the system will return "status": "failed", and the modification will not be applied.

Solution:

If you need to modify a prepaid online payment booking:

1. Review any applicable cancellation policy.
2. Cancel the existing booking.
3. Create a new order with the necessary changes.

This process ensures that the updated information is applied to your booking.

Modifying cancelled reservation

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 before attempting modifications using the /orders/details/accommodation endpoint. If the reservation has been cancelled, it may not be possible to change its dates.

• If you need to adjust dates, consider rebooking the reservation or creating a new one.

Room modification errors

Invalid parameters

This message is thrown when the request does not contain any valid parameters for room modification.

Example response:

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

Solution:

• Review the API documentation for the correct parameters required for room modifications.

• Double-check for any typos or missing data in the request.

Room reservation not found

This message is returned when the specified room reservation does not exist or is invalid.

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.

• Cross-check room details to confirm that the reservation exists in the system.

Guest number restriction

Returned when the number of guests cannot be changed because the applied rate is linked to the overall selected number of guests.

Example response:

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

Solution:

• Please 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 maximum allowed for the room.

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 provided is invalid (e.g. 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 and not zero or a negative value.
• If you need to add guests, update the number to a valid figure according to room capacity.

Unchanged guest number

Returned when the new guest number is the same as the existing one.

Example response:

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

Solution:

• If no changes are necessary, refrain from sending the modification request.

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

Smoking preference restriction

This message is retrieved when trying 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:

• Use the /orders/details endpoint passing the extras.room parameter in the request to verify the smoking preference of the room before attempting to update it.

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 of request:

{
  "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.