Cancel

POST /api/trade/cancel

Cancels a hotel booking order, validating order state and recording an audit trail as the cancellation is processed.

Both full and partial cancellation are supported; which one applies is determined by supplier policy and by the current state of the order.

Critical Prerequisites:

• Order ID: Must be provided to identify the target order
• JWT Authentication: Bearer token required in Authorization header
• Valid Order State: Order must be in a cancellable state

Cancellation Types:

• Full Cancellation: Complete order cancellation (most common)
• Partial Cancellation: Cancel specific nights or rooms (supplier-dependent)
• State-Dependent: Cancellation rules vary by order status and supplier policies

Enterprise Reliability Features:

• Order state machine validation and transitions
• Comprehensive audit logging and tracking
• Automatic rollback on processing failures
• CQRS event publishing for downstream processing
• Processing time monitoring and performance tracking

State Validation:

• Validates order exists and is accessible
• Checks current order state for cancellation eligibility
• Prevents cancellation of non-cancellable orders
• Returns appropriate validation errors for invalid states

Processing Flow:

1. Validate order existence and accessibility
2. Check order state for cancellation eligibility
3. Update order state to NeedCancel
4. Publish cancellation event to CQRS queue
5. Handle rollback if processing fails
6. Record comprehensive audit logs

Error Handling:

• Order not found errors with appropriate HTTP status
• State validation errors for non-cancellable orders
• Downstream timeout errors for supplier delays
• Automatic rollback on critical processing failures

Common Use Cases:

• Customer-initiated order cancellations
• Administrative order cancellations
• Policy-based cancellation processing
• Order lifecycle management

Request headers

Request body

Example request

{
  "customerReferenceNo": "9d1f4b2a-7c60-4f3e-9a58-1b0c2d3e4f50",
  "supplierReferenceNo": "TTD-2609-004871",
  "reason": "Guest cancelled within the free-cancellation window"
}

Response

Successful calls return the standard envelope. code is 0 on success — check it rather than the HTTP status alone, because some business failures are delivered with HTTP 200.

Example response

{
  "code": 0,
  "msg": "string",
  "data": {
    "serviceFee": {
      "currency": "USD",
      "amount": 0
    },
    "status": 0
  }
}

Failure responses

Every failure uses the { code, msg } envelope. See Error handling for the full business-code table.