MIGRATION GUIDES
/
v3.2 Migration
/
Orders endpoints
/
/orders/modify
Last updated

Orders modify – Migrating to v3.2

Detailed guide for integrating orders/preview flows with Demand API v3.2.

Introduction

The /orders/modify endpoint allows partners to update specific aspects of existing accommodation orders — for example, to adjust guest details, change dates, update room allocations, or modify payment details.

This guide explains the changes introduced in Demand API v3.2 for the /orders/modify endpoint compared to v3.1, and how to update your integration accordingly.

Breaking changes

Breaking changes

The following v3.1 fields are deprecated or replaced in v3.2. Update your integration to avoid disruption.

AreaChangeDescription
IdentifiersData type change.All reservation-related IDs (reservation, room_reservation) must now be sent as strings instead of numeric values.
PaymentModificationField requirement change.The order field is no longer required for PaymentModification objects.

Overview of all updates

Change areaSummary
Type consistencySeveral fields now use string instead of integer or long for better cross-language compatibility.
Required fieldsThe order field requirement has been relaxed for PaymentModification objects.
Validationv3.2 enforces stricter type validation for reservation and room_reservation IDs.
No structural changes in responsesThe overall schema structure, request patterns, and response format remain backward-compatible.

Request schema changes

Identifier type alignment

In v3.1, several ID fields were typed as integer or long.

In v3.2, all IDs are now strings fields to ensure cross-language consistency and prevent numeric precision issues.

Field pathv3.1 typev3.2 typeobject
modification.accommodation.reservationintegerstringAccommodationModification
modification.accommodation.change.room_reservationlongstringRoomChange

Action required

  • Update your integration to send these identifiers as strings rather than numeric values.
  • If your system currently serialises these as numbers, ensure conversion before making the API request.

Updated required fields for PaymentModification

In v3.1, the order field was required at the top level of all modification types.

In v3.2, it remains required for AccommodationModification, but is now optional for PaymentModification.

Objectv3.1 required fieldsv3.2 required fields
PaymentModificationorder, modificationmodification only

Action required

  • If your integration always sends order for Payment modifications, you can safely continue to include it — the field will be ignored if redundant.
  • However, ensure your schema or validation rules (if any) do not enforce it as mandatory for payment modifications.

Validation tightening

v3.2 enforces stricter data validation on ID and date fields.

Make sure your integration complies with the following:

  • checkin and checkout must use YYYY-MM-DD format.
  • expiry_date for card details must follow YYYY-MM.
  • accommodation.type must be either dates or room.

Sending numeric values where strings are expected will result in validation errors.

Example request comparison

{
  "order": "12345",
  "modification": {
    "accommodation": {
      "reservation": 67890,
      "type": "dates",
      "change": {
        "checkin": "2025-07-01",
        "checkout": "2025-07-03"
      }
    }
  }
}

Response schema changes

The 200 response remains structurally unchanged. Both modification types (AccommodationModificationResponse and PaymentModificationResponse) remain structurally identical between v3.1 and v3.2.

However:

  • Response validation now expects consistent data types — for example, price and status objects follow stricter type enforcement.
  • The status field continues to accept only successful or failed values.

Example (unchanged response):

{
  "modification": {
    "accommodation": {
      "new_price": 245.50,
      "status": "successful"
    }
  }
}

Implications for migration

Breaking changes:

  • All reservation-related IDs (reservation, room_reservation) must be sent as strings. Sending numeric values will fail validation.
  • Omitting order in PaymentModification is now allowed; any integration schema validation should be updated accordingly.

Non-breaking changes:

  • Response handling does not need to change.
  • All other fields can remain as-is.

Migration checklist

Checklist
Action
☑Convert all numeric IDs (reservation, room_reservation) to strings.
☑Verify date formats use ISO 8601 (YYYY-MM-DD for stay dates, YYYY-MM for expiry).
☑Adjust internal schema validation for PaymentModification to allow missing order field.
☑Test both accommodation and payment modification flows in the sandbox environment with test hotels.
☑Validate error handling for invalid data types and formats.

Testing and validation

Before deploying to production, confirm the following through sandbox testing:

  • At least one accommodation modification (date or room)
  • One payment modification (card details update)
  • Error handling for invalid ID types and date formats. See the Error handling guide.

Once these tests pass, your integration is fully compatible with Demand API v3.2.

What's next

Previous page
Next page