Cancel Booking

curl -X POST "$UNIFYSTAYS_BASE_URL/hotels/book/ubk_eGQ0dW9uV1Vi/cancel" \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "Idempotency-Key: cancel-order-2987349823" \
  -d '{"cancellation_quote_id":"cq_6c4f6abf5bbc4c6eae53e0d7411389a8"}'

{
  "contract_version": "2",
  "success": true,
  "message": "Cancellation request is pending with supplier.",
  "data": {
    "booking_id": "ubk_eGQ0dW9uV1Vi",
    "accepted_offer_id": "off_65db5f20d91b47d3a73d834dfa44c50e",
    "status": "CANCELLATION_PENDING",
    "is_terminal": false,
    "provider": {
      "code": "TRIPJACK",
      "booking_id": "TJ202487947162",
      "booking_code": null,
      "hotel_confirmation_number": "HCN-482910",
      "hotel_confirmation_status": "Confirmed",
      "hotel_confirmation_note": null,
      "hotel_contact_phone": null,
      "hotel_contact_name": null
    },
    "next_poll_after_ms": 5000,
    "processing_reason": "CANCELLATION_PENDING",
    "action_required": false,
    "available_actions": ["GET_STATUS", "GET_DETAILS"],
    "review_expires_at": null,
    "hold_deadline_at": null,
    "created_at": "2026-04-15T12:12:11.000Z",
    "updated_at": "2026-05-18T10:01:30.000Z"
  }
}

POST

hotels

book

{booking_id}

cancel

curl -X POST "$UNIFYSTAYS_BASE_URL/hotels/book/ubk_eGQ0dW9uV1Vi/cancel" \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "Idempotency-Key: cancel-order-2987349823" \
  -d '{"cancellation_quote_id":"cq_6c4f6abf5bbc4c6eae53e0d7411389a8"}'

{
  "contract_version": "2",
  "success": true,
  "message": "Cancellation request is pending with supplier.",
  "data": {
    "booking_id": "ubk_eGQ0dW9uV1Vi",
    "accepted_offer_id": "off_65db5f20d91b47d3a73d834dfa44c50e",
    "status": "CANCELLATION_PENDING",
    "is_terminal": false,
    "provider": {
      "code": "TRIPJACK",
      "booking_id": "TJ202487947162",
      "booking_code": null,
      "hotel_confirmation_number": "HCN-482910",
      "hotel_confirmation_status": "Confirmed",
      "hotel_confirmation_note": null,
      "hotel_contact_phone": null,
      "hotel_contact_name": null
    },
    "next_poll_after_ms": 5000,
    "processing_reason": "CANCELLATION_PENDING",
    "action_required": false,
    "available_actions": ["GET_STATUS", "GET_DETAILS"],
    "review_expires_at": null,
    "hold_deadline_at": null,
    "created_at": "2026-04-15T12:12:11.000Z",
    "updated_at": "2026-05-18T10:01:30.000Z"
  }
}

This is step 2 of cancelling. Step 1 is Quote Cancellation, which returns the penalty and a quote_id. Show the penalty to the user, and only after they accept, send that quote_id here together with an Idempotency-Key.

The cancellation flow

Check that cancelling is possible

The booking’s available_actions (from Get Booking Status) contains CANCEL. This is true for CONFIRMED and ON_HOLD bookings.

Get a quote

Call Quote Cancellation. Show penalty_status, penalty and the policy to the user.

Cancel with the quote

Send cancellation_quote_id before expires_at. Use a new Idempotency-Key for this cancellation.

Follow the outcome

The response is CANCELLED or CANCELLATION_PENDING. Poll status until it is CANCELLED.

Request example

curl -X POST "$UNIFYSTAYS_BASE_URL/hotels/book/ubk_eGQ0dW9uV1Vi/cancel" \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "Idempotency-Key: cancel-order-2987349823" \
  -d '{"cancellation_quote_id":"cq_6c4f6abf5bbc4c6eae53e0d7411389a8"}'

Response example

The response is a booking status object, the same as Get Booking Status.

{
  "contract_version": "2",
  "success": true,
  "message": "Cancellation request is pending with supplier.",
  "data": {
    "booking_id": "ubk_eGQ0dW9uV1Vi",
    "accepted_offer_id": "off_65db5f20d91b47d3a73d834dfa44c50e",
    "status": "CANCELLATION_PENDING",
    "is_terminal": false,
    "provider": {
      "code": "TRIPJACK",
      "booking_id": "TJ202487947162",
      "booking_code": null,
      "hotel_confirmation_number": "HCN-482910",
      "hotel_confirmation_status": "Confirmed",
      "hotel_confirmation_note": null,
      "hotel_contact_phone": null,
      "hotel_contact_name": null
    },
    "next_poll_after_ms": 5000,
    "processing_reason": "CANCELLATION_PENDING",
    "action_required": false,
    "available_actions": ["GET_STATUS", "GET_DETAILS"],
    "review_expires_at": null,
    "hold_deadline_at": null,
    "created_at": "2026-04-15T12:12:11.000Z",
    "updated_at": "2026-05-18T10:01:30.000Z"
  }
}

Request fields

Field	What it means	How to use it
`Idempotency-Key` (header)	A unique key for this cancellation, up to 128 characters. Required.	Generate it once per cancellation. Reuse it with the same body when you retry after a timeout.
`cancellation_quote_id` (body)	The `quote_id` the user accepted.	Send it unchanged. It must belong to this booking, be unexpired and unused.
`booking_id` (path)	The Unifystays booking ID.	The booking you quoted.

Outcomes

Status in the response	Meaning	What to do
`CANCELLED`	The cancellation is complete.	Show the final outcome. Read any charge in `cancellation_outcome.charge` from Get Booking Details.
`CANCELLATION_PENDING`	The supplier accepted it and is still processing.	Do not tell the guest it is cancelled yet. Poll status, or wait for the `booking.cancelled` webhook.

CANCELLATION_PENDING can also be the result when the supplier’s answer was uncertain. Unifystays then verifies the real outcome. The booking stays CANCELLATION_PENDING until that is known, and available_actions can include CONTACT_SUPPORT if it cannot be resolved.

Errors and retries

Result	Meaning	What to do
`400` `CANCELLATION_QUOTE_REQUIRED`	`cancellation_quote_id` is missing.	Get a quote first.
`400` `IDEMPOTENCY_KEY_REQUIRED`	The header is missing.	Send `Idempotency-Key`.
`409` `CANCELLATION_QUOTE_INVALID`	The quote is expired, already used, or not for this booking. This also happens when the penalty window changed and the old quote expired.	Request a new quote, show the new penalty, and ask again.
`409` `IDEMPOTENCY_KEY_REUSED`	The key was already used with a different quote.	Use a new key for a new quote.
`409` `CANCELLATION_IN_PROGRESS`	The same cancellation is still being processed.	Retry after a few seconds, or poll status.
`409` `CANCELLATION_REJECTED`	The supplier refused the cancellation. The booking stays active.	Keep the booking as it is and show the current state.
`409` `VALIDATION_ERROR`	The booking is not in a cancellable status.	Read the status.
`404` `BOOKING_NOT_FOUND`	Unknown booking, or it belongs to another organization.	Check the ID and API key.
`501`	The supplier does not support cancellation through the API.	Do not offer cancellation.

Retrying with the same Idempotency-Key and the same quote returns the same result. It never cancels twice. Calling cancel on a booking that is already CANCELLED or CANCELLATION_PENDING returns its current state.

If the penalty changes between the quote and the click, the quote is no longer valid and the cancel call fails with CANCELLATION_QUOTE_INVALID. Nothing is cancelled. Always request a fresh quote and show the new penalty before trying again.

penalty_status: UNKNOWN means no reliable amount exists. Do not display it as zero. Accepting that quote means the user accepts an unknown charge.

Keep the booking_id and the X-Request-Id response header in your support record.

Authorizations

x-api-key

string

header

required

Environment-specific API key created in the Unifystays portal

Headers

Idempotency-Key

string

required

Unique key (up to 128 characters) for this cancellation attempt. Reuse the same key and the same quote_id when retrying after a timeout.

X-Unifystays-Contract-Version

enum<string>

default:2

Hotel API contract version. Optional: 2 is the current version and the default.

Available options:

2

X-Unifystays-Currency

string

ISO 4217 currency for display amounts (display_ledger, display_amount, commercial_display). Optional: defaults to your organization's display currency, USD unless configured. Read pricing.display_currency in the response.

Required string length: 3

Example:

"EUR"

Path Parameters

booking_id

string

required

Unifystays booking ID returned by Create Booking (ubk_...).

Example:

"ubk_eGQ0dW9uV1Vi"

Body

application/json

cancellation_quote_id

string

required

The quote_id from Cancellation Quote that the user accepted. Must belong to this booking, be unexpired and unused.

Example:

"cq_6c4f6abf5bbc4c6eae53e0d7411389a8"

Response

contract_version

string

required

Response contract version. Always "2".

Example:

"2"

success

boolean

required

false only when the booking status is FAILED. true for every other status, including AWAITING_REVIEW and PROCESSING, which are not confirmations. Read data.status for the real state.

Example:

true

message

string

required

Human-readable summary for logs and support; for FAILED it carries the reason. Do not parse it; use data.status.

Example:

"Booking request accepted and is being processed."

data

object

required

The booking's current state.

Show child attributes

Overview

Destination & master data

Search & hotels

Bookings

Webhook endpoints

Webhook logs

The cancellation flow

Request example

Response example

Request fields

Outcomes

Errors and retries

Authorizations

Headers

Path Parameters

Body

Response

​The cancellation flow

​Request example

​Response example

​Request fields

​Outcomes

​Errors and retries

Authorizations

Headers

Path Parameters

Body

Response

The cancellation flow

Request example

Response example

Request fields

Outcomes

Errors and retries