Orders cancel – Migrating to v3.2

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

Introduction

This guide describes the structural and validation changes introduced in v3.2 for the /orders/cancel endpoint.

Version 3.2 introduces explicit multi-travel service support and refined validation, replacing the flat v3.1 schema. Existing integrations must update their request bodies to align with the new nested structure.

Breaking changes

Example – orders/cancel request

For an accommodation reservation

{
  "order": "509430129718799",
  "reason": "I would like to book another property instead of this one.",
  "request_property_approval": "true"
}

Key differences

Example - orders/cancel response

For v3.1 and v3.2

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

(Response structure remains unchanged)

Non-breaking improvements

Multi-travel service readiness - Unified structure prepares for future travel services beyond accommodation.

Deprecations

The following fields are deprecated in v3.1 and should be replaced with their updated equivalents.

Example migration workflow (step-by-step)

1. Schema inspection

• Retrieve the v3.2 OpenAPI schema for /orders/cancel.
• Review the new nested structure: accommodation and cars objects.

2. Update backend payload generation

• Replace top-level fields with the nested format.
• Map old fields:
  • order → accommodation.reservation
  • reason → accommodation.reason
  • request_property_approval → accommodation.request_property_approval (This is needed for the "Cancel for less" functionality - See guide for details)

3. Validation logic

• Ensure required fields are respected per travel service:
  • accommodation: reservation, reason

4. Response handling

• Keep existing success/failure handling logic; response structure unchanged.

5. Testing

• Test accommodation example using Sandbox environment and testing properties.
• Validate failure cases for missing required fields and invalid enum values.

6. Deployment

• Release with updated request format.
• Verify production logs for successful cancellations across supported travel services.

Migration checklist

Migration notes & tips

• Breaking format change - Requests must now use a nested travel service structure.
• Dual-read period - Maintain backward compatibility temporarily by checking both the old and new structures if necessary.
• Validation - Enforce strict required fields to prevent 400 responses.

What's next