> ## 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. # Create a Reservation > Book one slot on one service, allocating a table. Service, section and option ids come from [Get Availability](/platform/reservation/get-availability); `tagIds` come from [List Venue Tags](/platform/reservation/get-tags). ## OpenAPI ````yaml platform/reservation/openapi.json POST /venue/{venueId}/reservation 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}/reservation: post: tags: - Reservations summary: Create a reservation description: >- Creates a reservation for one slot on one service and allocates a table. Build the body from an availability response: `serviceId`, `sectionId` and every `menuOptionId` come straight from it. Availability is re-checked as the reservation is written, so a slot that has gone in the meantime returns `409` rather than double-booking. operationId: createReservation parameters: - $ref: '#/components/parameters/VenueId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateReservationRequest' example: localBookingDateAndTime: '2026-09-01T18:30:00' partySize: 2 serviceId: service_dinner sectionId: section_main firstName: Alex lastName: Chen email: alex.chen@example.com mobileNumber: '+61400000000' subscribed: true termsAgreementChecked: true emailSmsNotifications: false notes: Window table if possible tagIds: - tag_birthday selectedOptions: - menuOptionId: menuoption_set_menu quantity: 2 extras: - menuOptionId: menuoption_oysters quantity: 1 responses: '201': description: >- The reservation was written, with status Unconfirmed. Payment is not collected through this API, so `paymentDetails` comes back as `NoPayment` with `total: 0` even for a priced service. Read what the guest will owe at the venue from the availability response's `pricing`, never from here, and do not build a checkout step against this response. content: application/json: schema: $ref: '#/components/schemas/Reservation' example: id: booking_2026-09-01_G3F7PA8HO438Z_1787294227662 bookingRef: '94227662' status: U statusId: status_unconfirmed 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 - id: menuoption_oysters name: Half Dozen Oysters unitPrice: 1800 quantity: 1 paymentType: Deposit isUpsell: true paymentDetails: paymentType: NoPayment currency: AUD total: 0 paid: 0 state: None notes: Window table if possible source: online createdAt: '2026-08-27T04:45:00.104Z' '400': description: >- The body failed schema validation, the venue's booking settings refused the request, or the chosen booking options are not valid for the service. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' example: code: ValidationError message: Request body failed validation requestId: 0f1c9f2e-4b8a-4c1e-9d33-2a7f5b1c8e90 errors: firstName: - At least one of firstName or lastName is required localBookingDateAndTime: - Inside the venue's minimum notice period '404': $ref: '#/components/responses/NotFound' '409': description: >- No table could seat the party at that time, the slot went while the request was in flight, or a cap on booking options is already taken. Retry against fresh availability. content: application/json: schema: $ref: '#/components/schemas/DetailResponse' example: detail: No table can seat 2 at the requested time '500': $ref: '#/components/responses/ServerError' '501': description: >- The reservation needs a capability this endpoint does not have — currently, takeaway venues. content: application/json: schema: $ref: '#/components/schemas/DetailResponse' example: detail: Takeaway venues are not supported on this endpoint 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: CreateReservationRequest: type: object required: - localBookingDateAndTime - partySize - serviceId properties: localBookingDateAndTime: type: string description: >- Venue-local wall clock. A time component is required — a bare date means midnight, which is almost never a real sitting. Must be outside the venue's notice period and within its future-booking horizon. example: '2026-09-01T18:30:00' partySize: type: integer minimum: 1 maximum: 1000 description: Also limited by the venue's maximum party size. example: 2 serviceId: type: string minLength: 1 description: The service, by id — take it from the availability response. example: service_dinner sectionId: type: string description: >- Preferred section, by id. Absent — or the `any` / `all` sentinels — means no preference and the best match is picked. A named section that cannot seat the party fails with no fallback. example: section_main firstName: type: string maxLength: 100 description: >- Guest's first name. At least one of `firstName` / `lastName` is required; a missing pair is reported against `firstName`. lastName: type: string maxLength: 200 description: Guest's last name. email: type: string format: email maxLength: 250 description: >- Guest's email. At least one of `email` / `mobileNumber` is required; a missing pair is reported against `email`. mobileNumber: type: string maxLength: 20 description: Guest's mobile number, in international format. subscribed: type: boolean default: false description: >- Marketing consent. Recorded on the reservation and sent to the guest's customer record. termsAgreementChecked: type: boolean default: false description: >- Terms acceptance. Sent to the customer record only; the reservation does not carry it. emailSmsNotifications: type: boolean default: false description: >- **Not supported yet.** Accepted and recorded on the reservation, but it has no effect today: no confirmation email or SMS is sent for a reservation created through this API. Send your own guest confirmation. companyName: type: string maxLength: 100 description: Guest's company. Forwarded to the customer record. membershipNumber: type: string maxLength: 30 description: >- Accepted and forwarded to the guest's customer record. Not currently stored on the reservation itself. notes: type: string maxLength: 1000 description: Free-text note for the venue, e.g. a seating request. tagIds: type: array maxItems: 20 default: [] description: Tag ids from the tags endpoint. items: type: string minLength: 1 selectedOptions: type: array maxItems: 50 default: [] description: >- The booking options the guest chose. Which selections are allowed depends on the service — see the `pricing` and option lists in the availability response. A `quantity` of `0` is accepted and dropped, so you may post one entry per option on the menu. items: $ref: '#/components/schemas/SelectedOption' description: >- At least one of `firstName` / `lastName`, and at least one of `email` / `mobileNumber`, must be present. Unknown fields are ignored rather than rejected. The originating channel is taken from your credential. 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 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 DetailResponse: type: object description: >- The shape returned by the reservation write outcomes that are not validation failures — `409` and `501` on create, and `404` / `409` / `501` on update and cancel. required: - detail properties: detail: type: string SelectedOption: type: object required: - menuOptionId - quantity properties: menuOptionId: type: string minLength: 1 description: >- From the availability response's `menuOptions` or `menuOptionUpSellItems`. quantity: type: integer minimum: 0 maximum: 1000 description: >- How many of this option. `0` is accepted and dropped, so you may post one entry per option on the menu and zero out the ones the guest skipped. On a `PerPax` service the main options must total the party size, and when the service's pricing says `singleMenuPerBooking` the whole party takes exactly one main option. extras: type: array maxItems: 50 default: [] description: Child options under this one. items: type: object required: - menuOptionId - quantity properties: menuOptionId: type: string minLength: 1 quantity: type: integer minimum: 0 maximum: 1000 description: >- Which option and how many, only. Name, price, payment type and whether it is an upsell all come from the venue's own configuration. 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. 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: 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.