> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifystays.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Bookings

> List and filter bookings for the current organization for support, reconciliation, and operational workflows.

Use this endpoint for booking history, operational views, customer service, and
finance reconciliation. It returns paginated bookings belonging to the current
organization.

## Request Example

<RequestExample>
  ```bash theme={null}
  curl "$UNIFYSTAYS_BASE_URL/hotels/book?status=CONFIRMED&page=1&limit=20" \
    -H "x-api-key: $UNIFYSTAYS_API_KEY" \
    -H "language: en"
  ```
</RequestExample>

## Filter and Sort

The API supports free-text search across booking identifiers and hotel context,
along with filters for:

* Booking `status` and terminal state.
* Hotel, city, and provider.
* Stay dates and booking creation dates.
* Sort field, sort direction, page, and limit.

Use the returned `data.meta` for pagination and `data.summary` for aggregate
counts. For one booking's current state, call
[Get Booking Status](/api-reference/get-booking-status). For a full itinerary
or support record, call
[Get Booking Details](/api-reference/get-booking-details).

<Info>
  A list result is ideal for dashboards and support screens. Do not use a
  cached list row as the final truth for a booking that is currently processing
  or being cancelled; retrieve its latest status instead.
</Info>

The OpenAPI section below provides the complete filtering, sorting, pagination,
and response field reference.


## OpenAPI

````yaml reference/openapi.json GET /hotels/book
openapi: 3.0.0
info:
  title: Unifystays API
  description: >-
    One unified hotel API across suppliers. Integrate once, then enable and
    manage suppliers from the Unifystays portal.
  version: '1.0'
  contact: {}
servers:
  - url: https://api-sandbox.unifystays.com
    description: Sandbox
  - url: https://api.unifystays.com
    description: Production
security:
  - x-api-key: []
tags: []
paths:
  /hotels/book:
    get:
      tags:
        - Hotels
      summary: List bookings
      description: >-
        Returns paginated bookings for current org. Supports free-text search
        (booking ids/codes, HCN, hotel name, city, country), status filter, date
        ranges, provider/hotel/city filters, and sorting.
      operationId: HotelBookingController_listBookings
      parameters:
        - name: search
          required: false
          in: query
          description: >-
            Free-text search across booking ids/codes, HCN, hotel name, city,
            and country (case-insensitive).
          schema:
            example: ubk_
            type: string
        - name: status
          required: false
          in: query
          description: >-
            Filter by status. Accepts repeated values or CSV, e.g.
            `status=CONFIRMED&status=ON_HOLD` or `status=CONFIRMED,ON_HOLD`.
          schema:
            example:
              - CONFIRMED
              - PROCESSING
            type: array
            items:
              type: string
              enum:
                - PROCESSING
                - CONFIRMED
                - ON_HOLD
                - FAILED
                - CANCELLATION_PENDING
                - CANCELLED
        - name: hotel_id
          required: false
          in: query
          description: Filter by hotel id.
          schema:
            type: string
            example: '13553916'
        - name: city
          required: false
          in: query
          description: Filter by city (case-insensitive exact).
          schema:
            example: Dubai
            type: string
        - name: provider_code
          required: false
          in: query
          description: Filter by provider code.
          schema:
            type: string
            example: TRIPJACK
        - name: check_in_from
          required: false
          in: query
          description: Check-in date >= (YYYY-MM-DD).
          schema:
            example: '2026-05-01'
            type: string
        - name: check_in_to
          required: false
          in: query
          description: Check-in date <= (YYYY-MM-DD).
          schema:
            example: '2026-05-31'
            type: string
        - name: created_from
          required: false
          in: query
          description: Created date >= (ISO 8601).
          schema:
            example: '2026-04-01T00:00:00Z'
            type: string
        - name: created_to
          required: false
          in: query
          description: Created date <= (ISO 8601).
          schema:
            example: '2026-04-30T23:59:59Z'
            type: string
        - name: is_terminal
          required: false
          in: query
          description: Only return terminal (true) or non-terminal (false) bookings.
          schema:
            type: boolean
            example: false
        - name: sort_by
          required: false
          in: query
          description: Field to sort by.
          schema:
            default: created_at
            type: string
            enum:
              - created_at
              - check_in
              - check_out
              - total_payable_now
              - status
        - name: sort_order
          required: false
          in: query
          description: Sort direction.
          schema:
            default: DESC
            type: string
            enum:
              - ASC
              - DESC
        - name: page
          required: false
          in: query
          description: Page number (1-based).
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Results per page.
          schema:
            minimum: 1
            maximum: 100
            default: 20
            example: 20
            type: number
        - name: language
          description: Enter language code(ex. en)
          in: header
          schema: {}
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelBookingListResponseDto'
components:
  schemas:
    HotelBookingListResponseDto:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Bookings fetched successfully.
        data:
          $ref: '#/components/schemas/BookingListDataDto'
      required:
        - success
        - message
        - data
    BookingListDataDto:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BookingListItemDto'
        meta:
          $ref: '#/components/schemas/BookingListPaginationMetaDto'
        summary:
          $ref: '#/components/schemas/BookingListSummaryDto'
      required:
        - items
        - meta
        - summary
    BookingListItemDto:
      type: object
      properties:
        booking_id:
          type: string
          example: ubk_eGQ0dW9uV1Vi
        status:
          type: string
          enum:
            - PROCESSING
            - CONFIRMED
            - ON_HOLD
            - FAILED
            - CANCELLATION_PENDING
            - CANCELLED
          example: CONFIRMED
        is_terminal:
          type: boolean
          example: true
        hotel:
          $ref: '#/components/schemas/BookingListHotelDto'
        check_in:
          type: object
          example: '2026-05-26'
          nullable: true
        check_out:
          type: object
          example: '2026-05-28'
          nullable: true
        nights:
          type: object
          example: 2
          nullable: true
        rooms_count:
          type: object
          example: 1
          nullable: true
        guests_count:
          type: object
          example: 2
          nullable: true
        adults_count:
          type: object
          example: 2
          nullable: true
        children_count:
          type: object
          example: 0
          nullable: true
        total_payable_now:
          type: number
          example: 604577
          description: Total payable at booking (minor units).
        currency:
          type: object
          example: INR
          nullable: true
        provider_code:
          type: string
          example: TRIPJACK
        provider_booking_id:
          type: object
          example: TJ202487947162
          nullable: true
        provider_booking_code:
          type: object
          example: REZ6A5A81E9
          nullable: true
        hotel_confirmation_number:
          type: object
          example: HCN-482910
          nullable: true
        hotel_confirmation_status:
          type: object
          example: Confirmed
          nullable: true
        failure_code:
          type: object
          nullable: true
        failure_message:
          type: object
          nullable: true
        created_at:
          type: string
          example: '2026-04-15T12:12:11.000Z'
        updated_at:
          type: string
          example: '2026-04-15T12:12:11.000Z'
        completed_at:
          type: object
          example: '2026-04-15T12:15:11.000Z'
          nullable: true
      required:
        - booking_id
        - status
        - is_terminal
        - hotel
        - total_payable_now
        - provider_code
        - created_at
        - updated_at
    BookingListPaginationMetaDto:
      type: object
      properties:
        total:
          type: number
          example: 137
        page:
          type: number
          example: 1
        limit:
          type: number
          example: 20
        totalPages:
          type: number
          example: 7
        hasNextPage:
          type: boolean
          example: true
        hasPrevPage:
          type: boolean
          example: false
      required:
        - total
        - page
        - limit
        - totalPages
        - hasNextPage
        - hasPrevPage
    BookingListSummaryDto:
      type: object
      properties:
        total:
          type: number
          example: 137
          description: Total matching bookings across all pages.
        countsByStatus:
          type: object
          example:
            CONFIRMED: 110
            PROCESSING: 3
            ON_HOLD: 2
            FAILED: 15
            CANCELLATION_PENDING: 1
            CANCELLED: 6
          description: Count per unified status (scoped to active filters except `status`).
      required:
        - total
        - countsByStatus
    BookingListHotelDto:
      type: object
      properties:
        hotel_id:
          type: string
          example: '13553916'
        hotel_name:
          type: object
          example: Ramada Plaza by Wyndham Dubai Deira
          nullable: true
        city:
          type: object
          example: Dubai
          nullable: true
        country:
          type: object
          example: United Arab Emirates
          nullable: true
        stars:
          type: object
          example: 4
          nullable: true
      required:
        - hotel_id
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: Environment-specific API key created in the Unifystays portal

````