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

# List Bookings

> Retrieve a list of bookings with optional filters for date range, service, and customer details

<ParamField header="X-API-KEY" type="string" required>
  Your partner API key. Contact [platform.integrations@nowbookit.com](mailto:platform.integrations@nowbookit.com) to obtain one.
</ParamField>

## Query Parameters

<ParamField query="ServiceName" type="string">
  Filter bookings by service name (e.g., `"Dinner"`, `"Lunch"`).
</ParamField>

<ParamField query="StartDate" type="string">
  Start of the booking date range. **Required when `EndDate` is provided.**

  Format: `yyyy-MM-ddTHH:mm:ss.fffZ`

  Example: `2024-06-01T00:00:00.000Z`
</ParamField>

<ParamField query="EndDate" type="string">
  End of the booking date range. **Required when `StartDate` is provided.**

  Format: `yyyy-MM-ddTHH:mm:ss.fffZ`
</ParamField>

<ParamField query="UpdatedFromDate" type="string">
  Start of the last-modified date range. **Required when `UpdatedToDate` is provided.**

  Format: `yyyy-MM-ddTHH:mm:ss.fffZ`

  Use this pair to poll for changes since your last sync.
</ParamField>

<ParamField query="UpdatedToDate" type="string">
  End of the last-modified date range. **Required when `UpdatedFromDate` is provided.**

  Format: `yyyy-MM-ddTHH:mm:ss.fffZ`
</ParamField>

<ParamField query="IncludeCustomerDetails" type="boolean" default="false">
  When `true`, each booking object will include a nested `customer` object with the guest's contact details.
</ParamField>

<ParamField query="IncludeCancelledBookings" type="boolean" default="true">
  When `false`, cancelled bookings are excluded from results.
</ParamField>

<Warning>
  You must provide **either** `StartDate` + `EndDate` **or** `UpdatedFromDate` + `UpdatedToDate`. Mixing date filter types, or omitting both, will return an empty result set without an error response.
</Warning>

***

## Response

<ResponseField name="count" type="integer">
  Total number of bookings returned in this response.
</ResponseField>

<ResponseField name="bookings" type="array">
  List of booking objects.

  <Expandable title="Booking Object">
    <ResponseField name="bookingId" type="string">
      Unique NowBookIt booking identifier.
    </ResponseField>

    <ResponseField name="locationId" type="string">
      NowBookIt venue/location identifier.
    </ResponseField>

    <ResponseField name="method" type="string">
      How the booking was created (e.g., `"online"`, `"phone"`, `"walkin"`).
    </ResponseField>

    <ResponseField name="bookedAt" type="string">
      ISO 8601 timestamp of when the booking was created.
    </ResponseField>

    <ResponseField name="bookingTime" type="string">
      ISO 8601 datetime of the booking in venue local time.
    </ResponseField>

    <ResponseField name="duration" type="integer">
      Duration of the booking in minutes.
    </ResponseField>

    <ResponseField name="people" type="integer">
      Number of guests in the party.
    </ResponseField>

    <ResponseField name="customer" type="object">
      Customer details. Only present when `IncludeCustomerDetails=true`.

      <Expandable title="Customer Object">
        <ResponseField name="id" type="string">NowBookIt customer ID.</ResponseField>
        <ResponseField name="firstName" type="string">Customer first name.</ResponseField>
        <ResponseField name="lastName" type="string">Customer last name.</ResponseField>
        <ResponseField name="email" type="string">Customer email address.</ResponseField>
        <ResponseField name="phone" type="string">Customer phone number (international format).</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tables" type="array">
      List of table assignments for this booking.

      <Expandable title="Table Object">
        <ResponseField name="tableId" type="string">NowBookIt table identifier.</ResponseField>
        <ResponseField name="tableName" type="string">Human-readable table name.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tags" type="array">
      Tags associated with the booking.

      <Expandable title="Tag Object">
        <ResponseField name="tagType" type="string">Tag category.</ResponseField>
        <ResponseField name="name" type="string">Tag value.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Examples

<CodeGroup>
  ```bash Filter by date range theme={null}
  curl "https://{base_url}/Bookings?StartDate=2024-06-01T00:00:00.000Z&EndDate=2024-06-01T23:59:59.999Z&IncludeCustomerDetails=true" \
    -H "X-API-KEY: your_api_key"
  ```

  ```bash Poll for recent updates theme={null}
  curl "https://{base_url}/Bookings?UpdatedFromDate=2024-06-01T12:00:00.000Z&UpdatedToDate=2024-06-01T13:00:00.000Z" \
    -H "X-API-KEY: your_api_key"
  ```

  ```bash Filter by service theme={null}
  curl "https://{base_url}/Bookings?StartDate=2024-06-01T00:00:00.000Z&EndDate=2024-06-01T23:59:59.999Z&ServiceName=Dinner" \
    -H "X-API-KEY: your_api_key"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    `https://{base_url}/Bookings?StartDate=2024-06-01T00:00:00.000Z&EndDate=2024-06-01T23:59:59.999Z`,
    {
      headers: {
        "X-API-KEY": "your_api_key",
      },
    }
  );
  const data = await response.json();
  console.log(`${data.count} bookings returned`);
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "count": 2,
  "bookings": [
    {
      "bookingId": "bk_abc123",
      "locationId": "loc_xyz789",
      "method": "online",
      "bookedAt": "2024-05-28T09:14:22Z",
      "bookingTime": "2024-06-01T19:00:00",
      "duration": 90,
      "people": 4,
      "tables": [
        { "tableId": "tbl_001", "tableName": "Table 5" }
      ],
      "tags": [
        { "tagType": "occasion", "name": "Birthday" }
      ]
    },
    {
      "bookingId": "bk_def456",
      "locationId": "loc_xyz789",
      "method": "phone",
      "bookedAt": "2024-05-30T14:00:00Z",
      "bookingTime": "2024-06-01T20:30:00",
      "duration": 60,
      "people": 2,
      "tables": [],
      "tags": []
    }
  ]
}
```

***

## Status Codes

| Code  | Description                    |
| ----- | ------------------------------ |
| `200` | Success                        |
| `400` | API key not linked to a venue  |
| `401` | Invalid or missing `X-API-KEY` |
| `429` | Rate limit exceeded            |


## OpenAPI

````yaml GET /Bookings
openapi: 3.0.4
info:
  title: NowBookIt IPOS Partner API
  description: >-
    REST API for integrating your POS or external system with NowBookIt's
    reservation, sales, and gift card platform.
  version: v1
  contact:
    email: platform.integrations@nowbookit.com
servers:
  - url: https://ipos.dev.nowbookit.com
    description: Development
  - url: https://ipos.nowbookit.com
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /Bookings:
    get:
      tags:
        - Bookings
      summary: List Bookings
      operationId: listBookings
      parameters:
        - name: ServiceName
          in: query
          description: The Service Name.
          schema:
            type: string
        - name: StartDate
          in: query
          description: 'The Booking Start Date. Format: ''yyyy-MM-ddTHH:mm:ss.fffZ'''
          schema:
            type: string
        - name: EndDate
          in: query
          description: 'The Booking End Date. Format: ''yyyy-MM-ddTHH:mm:ss.fffZ'''
          schema:
            type: string
        - name: UpdatedFromDate
          in: query
          description: >-
            The Booking Updated From Start Date. Format:
            'yyyy-MM-ddTHH:mm:ss.fffZ'
          schema:
            type: string
        - name: UpdatedToDate
          in: query
          description: 'The Booking Updated To End Date. Format: ''yyyy-MM-ddTHH:mm:ss.fffZ'''
          schema:
            type: string
        - name: IncludeCustomerDetails
          in: query
          description: Set true to include customer details in the Bookings object.
          schema:
            type: boolean
        - name: IncludeCancelledBookings
          in: query
          description: >-
            Set False to exclude Bookings that are in Cancelled status. Default:
            True.
          schema:
            type: boolean
        - name: X-API-KEY
          in: header
          description: API Key authentication header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Gets Bookings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBookingsResponse'
        '404':
          description: >-
            Unable to find the Location Id for the POS or no Venue is subscribed
            to the Location.
        '500':
          description: An error occurred when retrieving bookings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    GetBookingsResponse:
      type: object
      properties:
        bookings:
          type: array
          items:
            $ref: '#/components/schemas/BookingModel'
          nullable: true
        count:
          type: integer
          format: int32
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    BookingModel:
      type: object
      properties:
        locationId:
          type: string
          description: The Pos System Location Id for the Venue.
          nullable: true
        bookingId:
          type: string
          description: The Unique booking id.
          nullable: true
        method:
          type: string
          description: The method used for booking.
          nullable: true
        bookedAt:
          type: string
          description: The UTC Date & Time when the booking was made.
          nullable: true
        bookingTime:
          type: string
          description: The booking time.
          nullable: true
        duration:
          type: integer
          description: Duration of Booking in minutes.
          format: int32
        people:
          type: integer
          description: Total number of people in booking.
          format: int32
        customer:
          $ref: '#/components/schemas/BookingModelCustomer'
        tables:
          type: array
          items:
            $ref: '#/components/schemas/BookingTable'
          nullable: true
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          nullable: true
        status:
          $ref: '#/components/schemas/BookingStatus'
        notes:
          type: string
          nullable: true
        paymentSummary:
          $ref: '#/components/schemas/PaymentSummary'
        serviceId:
          type: string
          nullable: true
        lastModifiedDate:
          type: string
          nullable: true
        serviceName:
          type: string
          nullable: true
        serviceType:
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
          nullable: true
      additionalProperties: false
    BookingModelCustomer:
      type: object
      properties:
        id:
          type: string
          description: The NBI Customer unique Id.
          nullable: true
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        company:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        phone:
          type: string
          description: Phone including international code.
          nullable: true
        address:
          $ref: '#/components/schemas/Address'
        phoneNational:
          type: string
          nullable: true
        phone2:
          type: string
          nullable: true
        birthdayDate:
          type: integer
          format: int32
          nullable: true
        birthdayMonth:
          type: integer
          format: int32
          nullable: true
        birthdayYear:
          type: integer
          format: int32
          nullable: true
        notes:
          type: string
          nullable: true
        noShowCount:
          type: integer
          format: int32
          nullable: true
        tags:
          type: array
          items:
            $ref: '#/components/schemas/CustomerTag'
          nullable: true
        subscribed:
          type: boolean
          description: The Customer Email Subscription status
        lastModifiedDate:
          type: string
          nullable: true
      additionalProperties: false
    BookingTable:
      type: object
      properties:
        tableId:
          type: string
          nullable: true
        tableName:
          type: string
          nullable: true
        sectionId:
          type: string
          nullable: true
        sectionName:
          type: string
          nullable: true
      additionalProperties: false
    Tag:
      type: object
      properties:
        tagType:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
      additionalProperties: false
    BookingStatus:
      type: object
      properties:
        statusType:
          type: string
          nullable: true
        code:
          type: string
          description: The Booking Status Code.
          nullable: true
        name:
          type: string
          description: The Booking Status string.
          nullable: true
      additionalProperties: false
    PaymentSummary:
      type: object
      properties:
        paymentType:
          type: string
          nullable: true
        amount:
          type: number
          format: double
        amountDue:
          type: number
          format: double
        transactionId:
          type: string
          nullable: true
        currencyCode:
          type: string
          nullable: true
        amountPaid:
          type: number
          format: double
        paymentDate:
          type: string
          nullable: true
      additionalProperties: false
    OrderItem:
      type: object
      properties:
        name:
          type: string
          nullable: true
        label:
          type: string
          nullable: true
        price:
          type: number
          format: double
        quantity:
          type: integer
          format: int32
        paymentType:
          type: string
          nullable: true
        extras:
          type: array
          items:
            $ref: '#/components/schemas/ExtraOrderItem'
          nullable: true
      additionalProperties: false
    Address:
      type: object
      properties:
        line1:
          type: string
          nullable: true
        line2:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        postalCode:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
      additionalProperties: false
    CustomerTag:
      type: object
      properties:
        id:
          type: string
          nullable: true
        identifier:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
      additionalProperties: false
    ExtraOrderItem:
      type: object
      properties:
        name:
          type: string
          nullable: true
        label:
          type: string
          nullable: true
        price:
          type: number
          format: double
        quantity:
          type: integer
          format: int32
        paymentType:
          type: string
          description: >-
            Available values: PreAuth, Deposit, FullPayment, FunctionPayment,
            NoPayment
          nullable: true
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````