# 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).

Important
Modifications must be submitted one type at a time—card, dates, or room—in separate requests.

### Preview modifications (Optional, only in Beta)

If you are using v3.2 Beta, you can optionally check modifications before applying them.

You can validate and estimate changes using the /orders/modify/preview endpoint before calling /orders/modify.

[Learn more → Preview order modifications guide (Beta)](/demand/docs/orders-api/3.2/order-modify-preview)

### Supported modifications by payment timing:

| Modification type | [Pay at the property](/demand/docs/payments/overview#pay-at-the-property) | [Online payments](/demand/docs/payments/overview#online-payments) |
|  --- | --- | --- |
| **Credit card details** | ✅ Supported | ❌ Not supported |
| **Check-in and check-out dates** | ✅ Supported | ❌ Not supported |
| **Room-level details**(guest allocation, guest names, smoking preferences) | ✅ Supported | ✅ Supported |


## Endpoint usage

When making a request to the [orders/modify endpoint](/demand/docs/open-api/demand-api/orders/orders/modify), you must include:

### Request body

The request body always includes:

| Required | Parameter | Description |
|  --- | --- | --- |
| ✓ | `order` | The order ID (string) of the booking to modify. |
| ✓ | `modification` | Object containing the modification details. This object varies by modification type:* `payment` - For card updates.
  * Include `type` = `"card"` and `change` object.
* `accommodation` - For dates or room updates.
  * Include `reservation` (string), `type` ("dates" or "room"), and `change` object.

 |


## 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


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

### Example response - Successful card modification


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

Refer to the [Credit card payments](/demand/docs/payments/payments-examples2#2.-create-your-order) section for best practices when using a cards as payment method.

## 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**.


Modifying dates may change the total price. Check availability and pricing via the accommodations/availability endpoint before updating.

### Example request - Dates modification


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


```json
{
  "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").


Use [/orders/details/accommodations endpoint](/demand/docs/open-api/demand-api/orders/orders/details/accommodations) to retrieve the `room_reservation` IDs located under "products" in each object. The `room_reservation` ID is required for all room-level modifications.

### Example request - Room modification


```json
{
  "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


```json
{
  "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](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) to check availability and view updated pricing before modifying the reservation.
2. If the price is not acceptable, cancel and create a new order.


See [the Accommodation quick guide](/demand/docs/accommodations/accommodation-quick-guide#3.-get-availability-and-prices) for usage examples.

## 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:


```json
{
  "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](/demand/docs/open-api/demand-api/orders/orders/preview).
* 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:


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

**Solution:**

* Retrieve reservation details using the [/orders/details/accommodations endpoint](/demand/docs/open-api/demand-api/orders/orders/details/accommodations)
* 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:


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

**Solution:**

* Check the reservation status using the [/orders/details/accommodations endpoint](/demand/docs/open-api/demand-api/orders/orders/details/accommodations).
* 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.


Refer to the [Create your orders guide](/demand/docs/orders-api/order-preview-create) for instructions on making new bookings.

### Room modification errors

#### No valid change parameter specified

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

Example response:


```json
{
  "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:


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

**Solution:**

* Use the [/orders/details/accommodations endpoint](/demand/docs/open-api/demand-api/orders/orders/details/accommodations) 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:


```json
{
  "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:


```json
{
  "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](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) 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.


Check the [Occupancy use cases](/demand/docs/accommodations/occupancy-use-cases#occupancy---use-cases) for more details and examples.

#### Invalid guest number

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

Example response:


```json
{
  "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:


```json
{
  "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:


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

**Solution:**

1. Call the [/orders/details endpoint](/demand/docs/open-api/demand-api/orders/orders/details) 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:


```json
{
  "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:


```json
      "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:


```json
{
  "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](/demand/docs/open-api/demand-api/orders/orders/details) 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.


Curious to know more?
* Find more errors in the [general Error handling](//demand/docs/support/error-handling/about-errors) guide and the [payment related errors](//demand/docs/support/error-handling/payment-errors) section.
* Check the [Cancellations guide](/demand/docs/orders-api/cancel-order) in case you need to cancel the order instead.
* Refer to the [orders/details guides](/demand/docs/orders-api/order-details) to learn how to retrieve details of your modified order.