> ## 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 Reservations > A venue's reservations over a calendar-date range. For a single reservation whose `id` you already hold, use [Get a Reservation](/platform/reservation/get-reservation) instead. ## OpenAPI ````yaml platform/reservation/openapi.json GET /venue/{venueId} openapi: 3.0.4 info: title: NowBookIt Reservation API description: >- REST API for venue availability and reservation lifecycle. Every endpoint is venue-scoped: `/api/reservations/venue/{venueId}/...`. version: v1 contact: email: platform.integrations@nowbookit.com servers: - url: https://platform.uat.nowbookit.com/api/reservations description: UAT - url: https://platform.nowbookit.com/api/reservations description: Production security: - ApiKeyAuth: [] tags: - name: Availability description: What a venue can offer for a party size over a date range. - name: Reservations description: List, read, create, amend and cancel a venue's reservations. - name: Reference data description: A venue's own guest tags and reservation statuses. paths: /venue/{venueId}: get: tags: - Reservations summary: List reservations description: >- A venue's reservations over an inclusive calendar-date range, ordered chronologically by date. Every reservation type is included — a standby or waitlist entry is the same kind of record as a confirmed booking, distinguished by `reservationType`. There is no status filter and no pagination: filter client-side on `status`. A range with no reservations is `200` with `[]` — only an unknown venue is a `404`. operationId: listReservations parameters: - $ref: '#/components/parameters/VenueId' - name: startDate in: query required: true description: >- First calendar date in the range, inclusive. A bare calendar date — a time component is not accepted. schema: type: string format: date example: '2026-09-01' - name: endDate in: query required: false description: >- Last calendar date in the range, inclusive. Defaults to `startDate`. At most 14 days from `startDate`, counting both ends. schema: type: string format: date example: '2026-09-07' responses: '200': description: The venue's reservations in the range. content: application/json: schema: type: array items: $ref: '#/components/schemas/Reservation' example: - id: booking_2026-09-01_G3F7PA8HO438Z_1787294227662 bookingRef: '94227662' status: C statusId: status_confirmed reservationType: Booking bookingDateTime: '2026-09-01T18:30:00' durationMinutes: 120 partySize: 2 service: id: service_dinner name: Dinner diner: id: customer_9f2a1c firstName: Alex lastName: Chen email: alex.chen@example.com phone: '+61400000000' tableIds: - table_12 requestedSectionId: section_main tagIds: - tag_birthday optionsSelected: - id: menuoption_set_menu name: Set Menu unitPrice: 2500 quantity: 2 paymentType: Deposit isUpsell: false paymentDetails: paymentType: Deposit pricingType: PerPerson currency: AUD total: 5000 paid: 5000 state: Paid transactionId: pi_3Qw1xyz paidAt: '2026-08-24T04:15:22.481Z' notes: Window table if possible source: online createdAt: '2026-08-24T04:15:20.104Z' updatedAt: '2026-08-24T04:15:22.900Z' '400': $ref: '#/components/responses/ValidationFailed' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' components: parameters: VenueId: name: venueId in: path required: true description: The venue being addressed. Every endpoint on this API is venue-scoped. schema: type: string minLength: 1 example: '6247' schemas: Reservation: type: object description: >- A reservation. Absent optional fields are omitted from the JSON rather than sent as `null` or `[]`. required: - id - bookingDateTime - partySize - tableIds - tagIds - optionsSelected - paymentDetails properties: id: type: string description: The identifier that addresses this reservation. example: booking_2026-08-24_G3F7PA8HO438Z_1787294227662 bookingRef: type: string description: >- The reference you quote to a guest. A different identifier from `id`, and not usable as a path parameter. example: '94227662' status: $ref: '#/components/schemas/ReservationStatusCode' statusId: type: string description: >- The status's id. Several statuses can share one `code`, so this is what identifies the status the reservation is in — and the value a patch sets `status` to. example: status_seated_main reservationType: type: string enum: - Booking - WaitList - StandbyList description: >- A standby or waitlist entry is the same kind of record as a confirmed booking. bookingDateTime: type: string description: Venue-local wall clock, ISO formatted. Not an absolute instant. example: '2026-08-24T14:00:00' durationMinutes: type: integer example: 120 partySize: type: integer example: 2 service: type: object properties: id: type: string example: service_dinner name: type: string example: Dinner diner: type: object description: Guest details recorded on the reservation. properties: id: type: string description: The guest's customer record, when the reservation has one. firstName: type: string lastName: type: string email: type: string phone: type: string tableIds: type: array description: The tables allocated. Empty only for a standby or waitlist entry. items: type: string requestedSectionId: type: string description: >- The section the reservation asked for, which is often not where the allocated table sits. Absent when no preference was given. movedFromBookingId: type: string description: >- The reservation this one replaced, set when a reservation was moved to another calendar date. The same `id` coming back means an ordinary change; a new `id` with this set means a replacement, and the value names the reservation to stop tracking. example: booking_2026-08-24_G3F7PA8HO438Z_1787294227662 tagIds: type: array items: type: string optionsSelected: type: array description: >- Booking options the guest chose, with the prices that determined what was payable. items: $ref: '#/components/schemas/ReservationOption' paymentDetails: $ref: '#/components/schemas/ReservationPaymentDetails' notes: type: string source: type: string description: >- Originating channel. Read-only — set from your credential when the reservation is created. example: online createdAt: type: string format: date-time description: >- When the reservation was made. An absolute instant, unlike `bookingDateTime`. updatedAt: type: string format: date-time ReservationStatusCode: type: string enum: - U - P$ - C - X - NS - S - F - SP - TX description: >- The status code the reservation carries, joining onto the reservation-statuses endpoint's `code`. `U` unconfirmed, `P$` pending payment, `C` confirmed, `X` cancelled, `NS` cancelled no-show, `S` seated, `F` finished, `SP` standby pending, `TX` SMS sent or SMS failed. Several statuses can share one code, so treat `code` as a coarse grouping and `statusId` as the precise value. Venues can add statuses of their own, so read the venue's own set from the reservation-statuses endpoint rather than assuming this list is closed. ReservationOption: type: object required: - id properties: id: type: string name: type: string unitPrice: type: number description: >- Per-unit. Multiply by `quantity` for this line's contribution to the total. quantity: type: integer paymentType: $ref: '#/components/schemas/PaymentType' isUpsell: type: boolean description: An optional extra rather than one of the main choices. ReservationPaymentDetails: type: object description: >- Where the reservation stands on payment. Always present, including for reservations that take no payment. required: - paymentType - total - paid - state properties: paymentType: $ref: '#/components/schemas/PaymentType' pricingType: allOf: - $ref: '#/components/schemas/PricingType' description: >- How the amount was arrived at. Never apply it to `total` — that value is already multiplied out. currency: type: string example: AUD total: type: number description: >- The amount payable, already multiplied out for the party. Not a per-guest rate. paid: type: number description: What was actually settled. `0` until paid. state: $ref: '#/components/schemas/PaymentState' transactionId: type: string description: Present once a payment exists. paidAt: type: string format: date-time dueBy: type: string format: date-time description: >- When the payment window closes. Present only while a payment is outstanding — it is how long the guest has to pay before the reservation is released. ValidationErrorResponse: allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object required: - errors properties: errors: type: object description: >- Field path to the messages for that field. A cross-field rule with no single field to blame is keyed `query`, `path` or `body`. additionalProperties: type: array items: type: string ErrorResponse: type: object required: - code - message - requestId properties: code: type: string description: >- The error class, e.g. `ValidationError`, `NotFoundError`, `InternalError`. example: NotFoundError message: type: string requestId: type: string description: Quote this when reporting a problem. PaymentType: type: string description: How the reservation takes payment, if at all. example: Deposit PricingType: type: string description: How the payable amount was arrived at — a label, not a multiplier. example: PerPerson PaymentState: type: string enum: - None - Pending - Paid - Holding - Completely Charged - Partially Charged - Released description: >- `None` nothing payable. `Pending` payable, nothing settled yet. `Paid` settled by a normal payment. The remaining four are pre-authorisation states, where funds are held rather than taken. responses: ValidationFailed: description: >- The request failed validation. `errors` is keyed by field path — `query`, `path` or `body` for an issue with no single field to blame. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' example: code: ValidationError message: Query parameters failed validation requestId: 0f1c9f2e-4b8a-4c1e-9d33-2a7f5b1c8e90 errors: partySize: - partySize must be at least 1 endDate: - endDate must be on or after startDate NotFound: description: >- The venue or reservation does not exist, or does not belong to the venue addressed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: NotFoundError message: 'Venue not found: 6247' requestId: 0f1c9f2e-4b8a-4c1e-9d33-2a7f5b1c8e90 ServerError: description: An unexpected failure. Quote `requestId` when reporting one. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: InternalError message: Internal server error requestId: 0f1c9f2e-4b8a-4c1e-9d33-2a7f5b1c8e90 securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- Your API key. See [Authorization](/platform/authorization) to create one. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.