List Bookings

curl "$UNIFYSTAYS_BASE_URL/hotels/book?status=CONFIRMED,ON_HOLD&check_in_from=2026-05-01&check_in_to=2026-05-31&page=1&limit=20" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY"

{
  "contract_version": "2",
  "success": true,
  "message": "Bookings fetched successfully.",
  "data": {
    "items": [
      {
        "booking_id": "ubk_eGQ0dW9uV1Vi",
        "status": "CONFIRMED",
        "is_terminal": true,
        "hotel": {
          "hotel_id": "13553916",
          "hotel_name": "Ramada Plaza by Wyndham Dubai Deira",
          "city": "Dubai",
          "country": "United Arab Emirates",
          "stars": 4
        },
        "check_in": "2026-05-26",
        "check_out": "2026-05-28",
        "nights": 2,
        "rooms_count": 1,
        "guests_count": 2,
        "adults_count": 2,
        "children_count": 0,
        "supplier_total": {
          "amount_minor": 36000,
          "currency": "USD",
          "currency_exponent": 2
        },
        "provider_code": "TRIPJACK",
        "provider_booking_id": "TJ202487947162",
        "provider_booking_code": null,
        "hotel_confirmation_number": "HCN-482910",
        "hotel_confirmation_status": "Confirmed",
        "failure_code": null,
        "failure_message": null,
        "created_at": "2026-04-15T12:12:11.000Z",
        "updated_at": "2026-04-15T12:15:11.000Z",
        "completed_at": "2026-04-15T12:15:11.000Z"
      }
    ],
    "meta": {
      "total": 137,
      "page": 1,
      "limit": 20,
      "totalPages": 7,
      "hasNextPage": true,
      "hasPrevPage": false
    },
    "summary": {
      "total": 137,
      "countsByStatus": {
        "CONFIRMED": 110,
        "PROCESSING": 3,
        "ON_HOLD": 2,
        "FAILED": 15,
        "CANCELLATION_PENDING": 1,
        "CANCELLED": 6
      }
    }
  }
}

GET

hotels

book

curl "$UNIFYSTAYS_BASE_URL/hotels/book?status=CONFIRMED,ON_HOLD&check_in_from=2026-05-01&check_in_to=2026-05-31&page=1&limit=20" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY"

{
  "contract_version": "2",
  "success": true,
  "message": "Bookings fetched successfully.",
  "data": {
    "items": [
      {
        "booking_id": "ubk_eGQ0dW9uV1Vi",
        "status": "CONFIRMED",
        "is_terminal": true,
        "hotel": {
          "hotel_id": "13553916",
          "hotel_name": "Ramada Plaza by Wyndham Dubai Deira",
          "city": "Dubai",
          "country": "United Arab Emirates",
          "stars": 4
        },
        "check_in": "2026-05-26",
        "check_out": "2026-05-28",
        "nights": 2,
        "rooms_count": 1,
        "guests_count": 2,
        "adults_count": 2,
        "children_count": 0,
        "supplier_total": {
          "amount_minor": 36000,
          "currency": "USD",
          "currency_exponent": 2
        },
        "provider_code": "TRIPJACK",
        "provider_booking_id": "TJ202487947162",
        "provider_booking_code": null,
        "hotel_confirmation_number": "HCN-482910",
        "hotel_confirmation_status": "Confirmed",
        "failure_code": null,
        "failure_message": null,
        "created_at": "2026-04-15T12:12:11.000Z",
        "updated_at": "2026-04-15T12:15:11.000Z",
        "completed_at": "2026-04-15T12:15:11.000Z"
      }
    ],
    "meta": {
      "total": 137,
      "page": 1,
      "limit": 20,
      "totalPages": 7,
      "hasNextPage": true,
      "hasPrevPage": false
    },
    "summary": {
      "total": 137,
      "countsByStatus": {
        "CONFIRMED": 110,
        "PROCESSING": 3,
        "ON_HOLD": 2,
        "FAILED": 15,
        "CANCELLATION_PENDING": 1,
        "CANCELLED": 6
      }
    }
  }
}

Use this endpoint for booking history, dashboards, customer service and finance reconciliation. It returns your organization’s bookings, newest first, with filters and pages. It is a read-only view over bookings you created with Create Booking.

When to call it

Build a “my bookings” or support screen.
Find a booking from a reference a guest or supplier gave you.
Reconcile: pull everything created or checking in within a date range.

A list row is a snapshot. For a booking that is PROCESSING or being cancelled, read Get Booking Status. For the full itinerary, read Get Booking Details.

Request example

curl "$UNIFYSTAYS_BASE_URL/hotels/book?status=CONFIRMED,ON_HOLD&check_in_from=2026-05-01&check_in_to=2026-05-31&page=1&limit=20" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY"

Response example

{
  "contract_version": "2",
  "success": true,
  "message": "Bookings fetched successfully.",
  "data": {
    "items": [
      {
        "booking_id": "ubk_eGQ0dW9uV1Vi",
        "status": "CONFIRMED",
        "is_terminal": true,
        "hotel": {
          "hotel_id": "13553916",
          "hotel_name": "Ramada Plaza by Wyndham Dubai Deira",
          "city": "Dubai",
          "country": "United Arab Emirates",
          "stars": 4
        },
        "check_in": "2026-05-26",
        "check_out": "2026-05-28",
        "nights": 2,
        "rooms_count": 1,
        "guests_count": 2,
        "adults_count": 2,
        "children_count": 0,
        "supplier_total": {
          "amount_minor": 36000,
          "currency": "USD",
          "currency_exponent": 2
        },
        "provider_code": "TRIPJACK",
        "provider_booking_id": "TJ202487947162",
        "provider_booking_code": null,
        "hotel_confirmation_number": "HCN-482910",
        "hotel_confirmation_status": "Confirmed",
        "failure_code": null,
        "failure_message": null,
        "created_at": "2026-04-15T12:12:11.000Z",
        "updated_at": "2026-04-15T12:15:11.000Z",
        "completed_at": "2026-04-15T12:15:11.000Z"
      }
    ],
    "meta": {
      "total": 137,
      "page": 1,
      "limit": 20,
      "totalPages": 7,
      "hasNextPage": true,
      "hasPrevPage": false
    },
    "summary": {
      "total": 137,
      "countsByStatus": {
        "CONFIRMED": 110,
        "PROCESSING": 3,
        "ON_HOLD": 2,
        "FAILED": 15,
        "CANCELLATION_PENDING": 1,
        "CANCELLED": 6
      }
    }
  }
}

Query parameters

Parameter	What it means	How to use it
`search`	Free text, 1 to 200 characters. Case-insensitive, matches anywhere in: booking ID, supplier booking ID and code, hotel confirmation number, hotel name, city, country.	One search box for support staff.
`status`	One or more statuses. Repeat the parameter or use commas: `status=CONFIRMED&status=ON_HOLD` or `status=CONFIRMED,ON_HOLD`.	Status tabs. Values: `AWAITING_REVIEW`, `PROCESSING`, `CONFIRMED`, `ON_HOLD`, `FAILED`, `CANCELLATION_PENDING`, `CANCELLED`.
`is_terminal`	`true`: finished bookings. `false`: bookings still in progress.	`is_terminal=false` gives a “needs watching” view.
`hotel_id`	Unifystays hotel ID.	All bookings for one hotel.
`city`	Exact city name, case-insensitive.	Filter by destination.
`provider_code`	Supplier code, case-insensitive (for example `TRIPJACK`).	Reconcile against one supplier.
`check_in_from`, `check_in_to`	Check-in on or after / on or before, as `YYYY-MM-DD`.	Arrivals in a date range.
`created_from`, `created_to`	Created at or after / at or before, ISO 8601 with a timezone, such as `2026-04-01T00:00:00Z`.	Reconciliation windows.
`sort_by`	`created_at` (default), `check_in`, `check_out`, `supplier_total`, `status`.	Choose the order.
`sort_order`	`DESC` (default) or `ASC`.	Newest first by default.
`page`	Page number, starting at 1.	Walk the pages.
`limit`	1 to 100, default 20.	Page size.

All filters combine with AND. Results are always limited to your organization.

Pagination and counts

data.meta.total is the number of bookings that match, across all pages.
Keep requesting page + 1 while data.meta.hasNextPage is true.
A page past the last returns an empty items list.
data.summary.countsByStatus counts bookings per status using every filter except status. Use it for tab counts while a status filter is applied. A status with no bookings is absent from the object.
data.summary.total equals meta.total.

Field guide

Field	What it means	How to use it
`items[].booking_id`	Unifystays booking ID.	Key for status, details and cancel.
`items[].status`, `is_terminal`	Booking status and whether it is final.	See Get Booking Status for meanings.
`items[].hotel`	Hotel ID, name, city, country, stars. Name, city, country and stars can be `null`.	Display. Use `hotel_id` to load hotel content.
`items[].check_in`, `check_out`, `nights`	Stay dates (`YYYY-MM-DD`) and length.	Display.
`items[].rooms_count`, `guests_count`, `adults_count`, `children_count`	Party size.	Display.
`items[].supplier_total`	Amount payable to the supplier, as Money: `amount_minor` (integer minor units) with `currency_exponent`.	Divide `amount_minor` by 10 to the power of `currency_exponent`. `null` when no currency is recorded.
`items[].display_total`	`supplier_total` in the display currency the booking was made with, as Money. It uses the exchange rate frozen when the booking was priced, so it never changes later and does not follow your current default currency.	Show it where you show prices. `null` for bookings made before display currencies existed.
`items[].display_fx`	The frozen rate behind `display_total`: `rate` (display currency per unit of booking currency), `rate_updated_at` (when the exchange-rate source last updated it; `null` when it gave none) and `frozen_at` (when the booking froze it).	Use for audit. `null` when `display_total` is `null`.
`items[].provider_code`	The supplier.	Informational and filterable.
`items[].provider_booking_id`, `provider_booking_code`	Supplier booking references.	Show to support. Not interchangeable.
`items[].hotel_confirmation_number`	The hotel’s confirmation number. `null` until the hotel confirms.	Show to guests when present.
`items[].failure_code`, `failure_message`	Why a booking failed. `null` otherwise.	Log the code. Do not parse the message.
`items[].created_at`, `updated_at`, `completed_at`	ISO 8601 UTC times. `completed_at` is `null` while in progress.	Display or sort.

A list row has less than the details record: no guests, rooms, cancellation policy or voucher data. Call Get Booking Details for those.

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"

Query Parameters

string

Free-text search (case-insensitive, matches anywhere in the value) across the Unifystays booking ID, supplier booking ID and code, hotel confirmation number, hotel name, city and country. 1 to 200 characters.

Example:

"ubk_"

status

enum<string>[]

Only return bookings in these statuses. Repeat the parameter or use a comma-separated list, e.g. status=CONFIRMED&status=ON_HOLD or status=CONFIRMED,ON_HOLD. Omit for all statuses.

Available options:

AWAITING_REVIEW,

PROCESSING,

CONFIRMED,

ON_HOLD,

FAILED,

CANCELLATION_PENDING,

CANCELLED

Example:

["CONFIRMED", "PROCESSING"]

hotel_id

string

Only return bookings for this Unifystays hotel_id (the hotel_id used in search and rooms).

Example:

"13553916"

city

string

Only return bookings whose hotel is in this city. Case-insensitive, exact match on the city name.

Example:

"Dubai"

provider_code

string

Only return bookings made through this supplier code (case-insensitive, for example TRIPJACK). Matches the provider_code on list items.

Example:

"TRIPJACK"

check_in_from

string

Only return bookings with check-in on or after this date (YYYY-MM-DD).

Example:

"2026-05-01"

check_in_to

string

Only return bookings with check-in on or before this date (YYYY-MM-DD).

Example:

"2026-05-31"

created_from

string

Only return bookings created at or after this instant (ISO 8601; include a timezone such as Z).

Example:

"2026-04-01T00:00:00Z"

created_to

string

Only return bookings created at or before this instant (ISO 8601; include a timezone such as Z).

Example:

"2026-04-30T23:59:59Z"

is_terminal

boolean

true: only finished bookings (CONFIRMED, ON_HOLD, FAILED, CANCELLED). false: only bookings still in progress (AWAITING_REVIEW, PROCESSING, CANCELLATION_PENDING). Omit for both.

Example:

false

sort_by

enum<string>

default:created_at

Field to sort by. supplier_total sorts by the booking amount. Ties are broken by newest booking first.

Available options:

created_at,

check_in,

check_out,

supplier_total,

status

sort_order

enum<string>

default:DESC

Sort direction: ASC or DESC. Newest first by default.

Available options:

ASC,

DESC

page

number

default:1

Page number, starting at 1. A page beyond the last returns an empty items list.

Required range: x >= 1

Example:

1

limit

number

default:20

Bookings per page, 1 to 100.

Required range: 1 <= x <= 100

Example:

20

Response

contract_version

string

required

Response contract version.

Example:

"2"

success

boolean

required

True when the request succeeded.

Example:

true

message

string

required

Human-readable summary. Do not parse it.

Example:

"Bookings fetched successfully."

data

object

required

The page of bookings with pagination and summary.

Show child attributes

Overview

Destination & master data

Search & hotels

Bookings

Webhook endpoints

Webhook logs

When to call it

Request example

Response example

Query parameters

Field guide

Authorizations

Headers

Query Parameters

Response

​When to call it

​Request example

​Response example

​Query parameters

​Pagination and counts

​Field guide

Authorizations

Headers

Query Parameters

Response

When to call it

Request example

Response example

Query parameters

Pagination and counts

Field guide