Get Booking Status

curl "$UNIFYSTAYS_BASE_URL/hotels/book/ubk_eGQ0dW9uV1Vi" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY"

{
  "contract_version": "2",
  "success": true,
  "message": "Booking confirmed successfully.",
  "data": {
    "booking_id": "ubk_eGQ0dW9uV1Vi",
    "accepted_offer_id": "off_65db5f20d91b47d3a73d834dfa44c50e",
    "status": "CONFIRMED",
    "is_terminal": true,
    "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": null,
    "processing_reason": null,
    "action_required": false,
    "available_actions": ["GET_DETAILS", "CANCEL"],
    "review_expires_at": null,
    "hold_deadline_at": null,
    "created_at": "2026-04-15T12:12:11.000Z",
    "updated_at": "2026-04-15T12:15:11.000Z"
  }
}

GET

hotels

book

{booking_id}

curl "$UNIFYSTAYS_BASE_URL/hotels/book/ubk_eGQ0dW9uV1Vi" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY"

{
  "contract_version": "2",
  "success": true,
  "message": "Booking confirmed successfully.",
  "data": {
    "booking_id": "ubk_eGQ0dW9uV1Vi",
    "accepted_offer_id": "off_65db5f20d91b47d3a73d834dfa44c50e",
    "status": "CONFIRMED",
    "is_terminal": true,
    "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": null,
    "processing_reason": null,
    "action_required": false,
    "available_actions": ["GET_DETAILS", "CANCEL"],
    "review_expires_at": null,
    "hold_deadline_at": null,
    "created_at": "2026-04-15T12:12:11.000Z",
    "updated_at": "2026-04-15T12:15:11.000Z"
  }
}

This is the endpoint you poll after Create Booking, Confirm Hold or Cancel Booking. It returns the status, whether the booking is final, the supplier and hotel references, and what you can do next. It does not return the itinerary. For that, call Get Booking Details. Booking is the last stage of the flow: search, rooms, prebook, book, then manage. This page covers the “manage” side.

When to call it

Right after a booking or cancellation that did not return a final status.
Whenever you receive a webhook and want the latest state.
Wait next_poll_after_ms between calls. Stop when is_terminal is true.
Prefer webhooks over tight polling. Polling is the fallback.

If you lost the booking_id (for example the create call timed out), use Find Booking by Idempotency-Key.

Request example

curl "$UNIFYSTAYS_BASE_URL/hotels/book/ubk_eGQ0dW9uV1Vi" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY"

Response example

{
  "contract_version": "2",
  "success": true,
  "message": "Booking confirmed successfully.",
  "data": {
    "booking_id": "ubk_eGQ0dW9uV1Vi",
    "accepted_offer_id": "off_65db5f20d91b47d3a73d834dfa44c50e",
    "status": "CONFIRMED",
    "is_terminal": true,
    "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": null,
    "processing_reason": null,
    "action_required": false,
    "available_actions": ["GET_DETAILS", "CANCEL"],
    "review_expires_at": null,
    "hold_deadline_at": null,
    "created_at": "2026-04-15T12:12:11.000Z",
    "updated_at": "2026-04-15T12:15:11.000Z"
  }
}

Booking statuses

Status	Terminal	What it means	What to do
`AWAITING_REVIEW`	No	Nothing is booked. The request waits for an organization owner or admin to approve it in the portal. This happens for non-refundable offers, expired free-cancellation windows and unclear cancellation terms.	Tell the user the booking is pending approval. Do not poll quickly. Wait for the webhook.
`PROCESSING`	No	The booking is being placed with the supplier.	Poll at `next_poll_after_ms`, or wait for `booking.confirmed` / `booking.failed`.
`CONFIRMED`	Yes	The booking is made.	Store the references and show the confirmation. See References.
`ON_HOLD`	Yes	The supplier holds the room but it is not final. Only for offers booked with `booking_mode: "HOLD"`.	Call Confirm Hold before `hold_deadline_at`, or cancel.
`FAILED`	Yes	The room was not booked. `success` is `false`.	Read the failure on the details record, then restart from search or rooms if the guest still wants to book.
`CANCELLATION_PENDING`	No	A cancellation was accepted and the supplier is still processing it.	Keep polling until `CANCELLED`.
`CANCELLED`	Yes	The booking is cancelled.	Show the outcome. Read any charge from the details record.

Terminal means “stop polling”, not “nothing more can happen”. A CONFIRMED booking can still be cancelled, and an ON_HOLD booking can still be confirmed. Both are your own actions.

Field guide

Booking

Field	What it means	How to use it
`data.booking_id`	The Unifystays booking ID (`ubk_...`).	Store it. It is the key for every later call.
`data.accepted_offer_id`	The offer this booking was made from.	Send it unchanged to Confirm Hold.
`data.status`	One of the statuses above.	Branch on it. Show it to your user in your own words.
`data.is_terminal`	`true` for `CONFIRMED`, `ON_HOLD`, `FAILED`, `CANCELLED`.	Stop polling when `true`.
`data.next_poll_after_ms`	Milliseconds to wait before the next poll. `null` for terminal bookings and for `AWAITING_REVIEW`.	Use it as your poll delay. `null` does not mean confirmed.
`data.created_at`, `data.updated_at`	ISO 8601 UTC times.	Display or log.
`message`	Plain-text summary.	Do not parse it.
`success`	`false` only when status is `FAILED`.	Do not treat a `200` as success on its own. Check `status`.

What to do next

Field	What it means	How to use it
`data.processing_reason`	Why the booking is not simply done. `null` when nothing is pending.	Use it to explain the wait. Values below.
`data.action_required`	`true` when someone must act: `available_actions` contains `CONFIRM_HOLD`, `CONTACT_SUPPORT` or `REVIEW_BOOKING`.	If `false`, waiting is enough.
`data.available_actions`	The actions you can take now. Values below.	Drive your buttons from this list, not from your own status logic.
`data.review_expires_at`	While `AWAITING_REVIEW`, the deadline of the current supplier quote.	Informational. If it passes, the request stays pending until a reviewer approves a fresh quote.
`data.hold_deadline_at`	While `ON_HOLD`, the time by which you must confirm.	Show a countdown. Confirm before it.

processing_reason values:

Value	Meaning
`SUPPLIER_CONFIRMATION_PENDING`	Waiting for the supplier to confirm.
`HOTEL_CONFIRMATION_PENDING`	The supplier confirmed. The hotel’s own confirmation number has not arrived yet.
`CANCELLATION_PENDING`	The supplier is processing a cancellation.
`RECONCILIATION_REQUIRED`	The supplier’s answer was uncertain. Unifystays is checking the real outcome. `available_actions` includes `CONTACT_SUPPORT`. Do not create a new booking.
`HOLD_CONFIRMATION_REQUIRED`	The booking is on hold and needs confirming.
`MANUAL_REVIEW_REQUIRED`	Waiting for approval in the portal.
`MANAGED_FULFILLMENT_PENDING`	Recorded, and not yet submitted to a supplier.

available_actions values:

Value	Meaning
`GET_STATUS`	Keep polling. Listed while the booking is not terminal, and during `CANCELLATION_PENDING`.
`GET_DETAILS`	The full record is readable. Always listed.
`CANCEL`	You can quote and cancel. Listed for `CONFIRMED` and `ON_HOLD` bookings whose supplier supports cancellation.
`CONFIRM_HOLD`	Call Confirm Hold.
`CONTACT_SUPPORT`	The outcome needs Unifystays support. Contact support with the `booking_id` and the `X-Request-Id` header.
`REVIEW_BOOKING`	Approve or reject the request in the portal.

References to show and store

Field	What it means	How to use it
`data.provider.code`	The supplier that holds the booking.	Informational. Do not branch logic on it.
`data.provider.booking_id`	The supplier’s primary booking or order ID. `null` until assigned.	Store it. Quote it to support. It is the supplier reference, not the guest’s hotel number.
`data.provider.booking_code`	A distinct secondary supplier code. `null` when the supplier uses only one reference.	Store it when present. Not interchangeable with `booking_id`.
`data.provider.hotel_confirmation_number`	The hotel’s own confirmation number. `null` until the hotel confirms. It can arrive after the booking is `CONFIRMED`.	Show it to the guest as the hotel confirmation number when present. If `null`, keep reading status or details until it appears.
`data.provider.hotel_confirmation_status`	Supplier text about the hotel confirmation.	Display only. Do not parse.
`data.provider.hotel_confirmation_note`	Free-text note about the confirmation.	Show to support or the guest when present.
`data.provider.hotel_contact_name`, `hotel_contact_phone`	Hotel contact for this booking, when the supplier gives one.	Optional guest information.

Common mistakes

Do not create a second booking because a booking is slow. A PROCESSING booking, including one with RECONCILIATION_REQUIRED, is still being resolved. Poll, or look it up with its Idempotency-Key.

A 404 BOOKING_NOT_FOUND also appears for a booking that belongs to another organization. Check that you use the same API key that created the booking.

Next step

Confirmed: show the booking details to the guest.
On hold: Confirm Hold.
Guest wants to cancel: Quote Cancellation.

Authorizations

x-api-key

string

header

required

Environment-specific API key created in the Unifystays portal

Headers

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"

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

When to call it

Request example

Response example

Booking statuses

Field guide

Booking

What to do next

References to show and store

Common mistakes

Next step

Authorizations

Headers

Path Parameters

Response

​When to call it

​Request example

​Response example

​Booking statuses

​Field guide

​Booking

​What to do next

​References to show and store

​Common mistakes

​Next step

Authorizations

Headers

Path Parameters

Response

When to call it

Request example

Response example

Booking statuses

Field guide

Booking

What to do next

References to show and store

Common mistakes

Next step