curl -X POST "$UNIFYSTAYS_BASE_URL/hotels/book/ubk_eGQ0dW9uV1Vi/cancellation-quote" \
-H "x-api-key: $UNIFYSTAYS_API_KEY"
{
"contract_version": "2",
"success": true,
"message": "Cancellation consequence quoted successfully.",
"data": {
"quote_id": "cq_6c4f6abf5bbc4c6eae53e0d7411389a8",
"booking_id": "ubk_eGQ0dW9uV1Vi",
"accepted_offer_id": "off_65db5f20d91b47d3a73d834dfa44c50e",
"expires_at": "2026-05-18T10:05:00.000Z",
"cancellable": true,
"penalty_status": "NO_CHARGE",
"penalty": {
"amount_minor": 0,
"currency": "USD",
"currency_exponent": 2
},
"cancellation": {
"refundability": "REFUNDABLE",
"policy_stage": "FINAL",
"free_cancellation_until": {
"local_datetime": "2026-05-20T23:59:59",
"timezone": "UTC",
"utc_datetime": "2026-05-20T23:59:59.000Z"
},
"policy_text": "Free cancellation until 20 May 2026.",
"penalties": [],
"no_show": null
}
}
}
Bookings
Quote Cancellation
Retrieve and lock the current cancellation consequence before cancelling.
POST
/
hotels
/
book
/
{booking_id}
/
cancellation-quote
curl -X POST "$UNIFYSTAYS_BASE_URL/hotels/book/ubk_eGQ0dW9uV1Vi/cancellation-quote" \
-H "x-api-key: $UNIFYSTAYS_API_KEY"
{
"contract_version": "2",
"success": true,
"message": "Cancellation consequence quoted successfully.",
"data": {
"quote_id": "cq_6c4f6abf5bbc4c6eae53e0d7411389a8",
"booking_id": "ubk_eGQ0dW9uV1Vi",
"accepted_offer_id": "off_65db5f20d91b47d3a73d834dfa44c50e",
"expires_at": "2026-05-18T10:05:00.000Z",
"cancellable": true,
"penalty_status": "NO_CHARGE",
"penalty": {
"amount_minor": 0,
"currency": "USD",
"currency_exponent": 2
},
"cancellation": {
"refundability": "REFUNDABLE",
"policy_stage": "FINAL",
"free_cancellation_until": {
"local_datetime": "2026-05-20T23:59:59",
"timezone": "UTC",
"utc_datetime": "2026-05-20T23:59:59.000Z"
},
"policy_text": "Free cancellation until 20 May 2026.",
"penalties": [],
"no_show": null
}
}
}
Cancelling is a two-step flow. This is step 1. It tells you what cancelling
costs right now and gives you a
No request body is needed.
quote_id. Show the penalty to the user. If
they accept, send the quote_id to Cancel Booking.
You cannot cancel without a quote.
Call it when the user asks to cancel, not earlier. A quote is short-lived, and
the penalty can change as the cancellation deadline passes.
Request example
curl -X POST "$UNIFYSTAYS_BASE_URL/hotels/book/ubk_eGQ0dW9uV1Vi/cancellation-quote" \
-H "x-api-key: $UNIFYSTAYS_API_KEY"
Response example
{
"contract_version": "2",
"success": true,
"message": "Cancellation consequence quoted successfully.",
"data": {
"quote_id": "cq_6c4f6abf5bbc4c6eae53e0d7411389a8",
"booking_id": "ubk_eGQ0dW9uV1Vi",
"accepted_offer_id": "off_65db5f20d91b47d3a73d834dfa44c50e",
"expires_at": "2026-05-18T10:05:00.000Z",
"cancellable": true,
"penalty_status": "NO_CHARGE",
"penalty": {
"amount_minor": 0,
"currency": "USD",
"currency_exponent": 2
},
"cancellation": {
"refundability": "REFUNDABLE",
"policy_stage": "FINAL",
"free_cancellation_until": {
"local_datetime": "2026-05-20T23:59:59",
"timezone": "UTC",
"utc_datetime": "2026-05-20T23:59:59.000Z"
},
"policy_text": "Free cancellation until 20 May 2026.",
"penalties": [],
"no_show": null
}
}
}
Penalty status
penalty_status | penalty | Meaning | What to show |
|---|---|---|---|
NO_CHARGE | A zero amount. | Cancelling now is free. | ”Free cancellation.” |
KNOWN | The amount that applies now. | The supplier’s policy has a charge for today. | The amount, formatted from amount_minor and currency_exponent. |
UNKNOWN | null | The supplier does not give a reliable amount for today. | Say the charge is not known. Never show it as zero. |
penalty.amount_minor is an integer in minor units. With currency_exponent
2, 17700 means 177.00. The currency is the booking’s currency.
Field guide
| Field | What it means | How to use it |
|---|---|---|
data.quote_id | The quote. Single use. | Send it as cancellation_quote_id to Cancel Booking, unchanged. |
data.expires_at | When the quote stops being valid (ISO 8601, UTC). Five minutes after issue, or sooner if the penalty is about to change. | Show a countdown. Cancel before it, or request a new quote. |
data.penalty_status | NO_CHARGE, KNOWN or UNKNOWN. | Drive the confirmation screen. |
data.penalty | The charge for cancelling now, or null. | Display it. |
data.cancellation | The policy the quote is based on, with penalties windows and free_cancellation_until. | Show the policy text next to the penalty. Do not recompute the charge from it. |
data.cancellable | Whether cancellation can go ahead. | Currently always true when a quote is returned. A booking that cannot be cancelled gets no quote. It returns an error instead. |
data.booking_id, data.accepted_offer_id | The booking and offer the quote is for. | Informational. |
What can go wrong
| Result | Meaning | What to do |
|---|---|---|
409 VALIDATION_ERROR | The booking is in a status that cannot be cancelled (for example FAILED, CANCELLED, or PROCESSING with no supplier confirmation yet), has no supplier reference, or has no stored policy. | Read the status. Check that available_actions contains CANCEL before offering cancellation. |
501 | The supplier does not support cancellation through the API. | Do not offer cancellation. Contact support. |
404 BOOKING_NOT_FOUND | Unknown booking ID, or it belongs to another organization. | Check the ID and API key. |
A quote is valid only until
expires_at and for one cancellation. If the
penalty changes before the user decides (for example a free-cancellation
deadline passes), the old quote is rejected by Cancel Booking with
CANCELLATION_QUOTE_INVALID. Request a new quote and show the new penalty.Requesting a quote does not cancel anything. You can request as many quotes as
you like.
Next step
Show the penalty. When the user confirms, call Cancel Booking with thequote_id.Authorizations
Environment-specific API key created in the Unifystays portal
Headers
Hotel API contract version. Optional: 2 is the current version and the default.
Available options:
2 Path Parameters
Unifystays booking ID returned by Create Booking (ubk_...).
Example:
"ubk_eGQ0dW9uV1Vi"
Response
Response contract version.
Example:
"2"
True when the quote was issued.
Example:
true
Human-readable summary. Do not parse it.
Example:
"Cancellation consequence quoted successfully."
The cancellation quote.
Show child attributes
Show child attributes