Cancel Booking

This endpoint cancels an existing booking through the Integration API.

PATCH/api/integration/booking/cancel

Request

cURL

curl -X PATCH "https://dev.integration.cl.sodtrack-shared.sodtrack.com/api/integration/booking/cancel" \
  -H "Authorization: Bearer $SODTRACK_TOKEN" \
  -H "origin: <your-origin>"

Base URL: https://dev.integration.cl.sodtrack-shared.sodtrack.com · other environments

Headers

Name	Type	Description
`origin`	string	—

General Description

This endpoint cancels an existing booking through the Integration API. The booking is identified in the request body by either booking ID or booking reference.

The endpoint optionally accepts dynamic form answers, for forms associated to the booking cancellation flow.

Field Definitions

Request Body: ExternalIntegrationCancelBookingRequestDTO

Field	Type	Required	Description
`booking`	ExternalIntegrationBookingIdentifierRequestDTO	Yes	Booking identifier object. Supports lookup by booking ID or booking reference.
`dynamicForms`	CreateDynamicFormSnapshotFromExternalIntegrationRequestDTO[]	No	Optional list of dynamic form answers to store as booking dynamic form snapshots on cancellation flow.

ExternalIntegrationBookingIdentifierRequestDTO

Field	Type	Required	Description
`type`	enum	Yes	Type of booking identifier. Must be one of: `bookingId` or `bookingReference`.
`value`	string	Yes	The booking ID (if type is `bookingId`) or booking reference (if type is `bookingReference`).

CreateDynamicFormSnapshotFromExternalIntegrationRequestDTO

Field	Type	Required	Description
`formReference`	string	Yes	Dynamic form reference configured in Sodtrack.
`values`	CreateBookingDynamicFormFieldValueV2RequestDTO[]	Yes	List of dynamic field answers for the form.

CreateBookingDynamicFormFieldValueV2RequestDTO

Field	Type	Required	Description
`fieldReference`	string	Yes	Dynamic form field reference to answer.
`value`	string	Yes	Value to persist for the selected field.

Success Response

Field	Type	Required	Description
-	-	-	`200 OK`. Response body is the cancelled booking (BookingDTO).

Business Rules & Constraints

The booking must exist (bookingId or bookingReference lookup). If not found, the endpoint returns BOOKING_NOT_FOUND_FOR_ID (when identifying by ID) or BOOKING_NOT_FOUND_FOR_REFERENCE (when identifying by reference).
When identifying by bookingReference, the reference must resolve to exactly one booking. If multiple bookings share the same reference, the endpoint returns MULTIPLE_BOOKINGS_FOUND_FOR_REFERENCE.
When identifying by bookingId, the value must be a valid numeric ID. Invalid values return INVALID_BOOKING_ID.
The booking must be in a cancellable status. Bookings in any of the following statuses cannot be cancelled: ON_MY_WAY_TO_ORIGIN, ARRIVED_TO_ORIGIN, ON_MY_WAY, ARRIVED_TO_DESTINATION, DONE, CANCELLED. If the booking is in one of these statuses, the endpoint returns 400 Bad Request with message "Booking cannot be cancelled".
dynamicForms is optional, and need an actual dynamic form configured in the platform. The dynamic form has to be associated to the booking cancellation flow and must to have references, at form and fields level, for each of the fields sent in the payload.

Example Request

json

{
  "booking": {
    "type": "bookingReference",
    "value": "BOOK-EXT-789"
  },
  "dynamicForms": [
    {
      "formReference": "booking-cancel-reasons-v1",
      "values": [
        {
          "fieldReference": "cancel_reason",
          "value": "customer_request"
        },
        {
          "fieldReference": "cancel_details",
          "value": "Customer requested cancellation via external system."
        }
      ]
    }
  ]
}

Example Response

http

HTTP/1.1 200 OK
Content-Type: application/json

Example Error Responses

Booking not found (by ID):

json

{
  "statusCode": 404,
  "message": "BOOKING_NOT_FOUND_FOR_ID",
  "error": "Not Found"
}

Booking not found (by reference):

json

{
  "statusCode": 404,
  "message": "BOOKING_NOT_FOUND_FOR_REFERENCE",
  "error": "Not Found"
}

Multiple bookings for same reference:

json

{
  "statusCode": 400,
  "message": "MULTIPLE_BOOKINGS_FOUND_FOR_REFERENCE",
  "error": "Bad Request"
}

Invalid booking ID (non-numeric):

json

{
  "statusCode": 400,
  "message": "INVALID_BOOKING_ID",
  "error": "Bad Request"
}

Booking cannot be cancelled (status not allowed):

json

{
  "statusCode": 400,
  "message": "Booking cannot be cancelled",
  "error": "Bad Request"
}