> ## 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. # Update a Reservation > Change an existing reservation. `status` takes an id from [Reservation Statuses](/platform/reservation/get-reservation-statuses). To cancel, use [Cancel a Reservation](/platform/reservation/cancel-reservation). ## OpenAPI ````yaml platform/reservation/openapi.json PATCH /venue/{venueId}/reservation/{id} 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/{id}: patch: tags: - Reservations summary: Update a reservation description: >- Changes an existing reservation. Only the fields you send are changed; an empty body is a `400`. **Changing the date returns a different reservation.** The reservation is recreated on the new day and the original cancelled, so the response carries a new `id` and a `movedFromBookingId` naming the old one. Store the new id. Changing the time, party size, service, section or table re-runs table allocation and can return `409`. Changing `status` or guest details does not, and a status-only change is accepted more widely — it still works after the reservation has started, inside the venue's change window, and on reservations that involve payment. To cancel, use the cancel endpoint; setting the cancelled status here is refused. operationId: updateReservation parameters: - $ref: '#/components/parameters/VenueId' - $ref: '#/components/parameters/ReservationId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateReservationRequest' example: partySize: 4 responses: '200': description: >- The updated reservation. After a date change this is the replacement, with a new `id`. content: application/json: schema: $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: 4 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 paymentDetails: paymentType: NoPayment currency: AUD total: 0 paid: 0 state: None source: online createdAt: '2026-08-24T04:15:20.104Z' updatedAt: '2026-08-28T04:45:00.104Z' '400': description: >- The body did not validate, the `status` does not exist at this venue, or the venue's booking settings refused the change. `errors` names the fields. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' example: code: ValidationError message: Request body failed validation requestId: 0f1c9f2e-4b8a-4c1e-9d33-2a7f5b1c8e90 errors: selectedOptions: - Required when partySize changes on a PerPax service '404': description: No such reservation at this venue, or no such venue. content: application/json: schema: oneOf: - $ref: '#/components/schemas/DetailResponse' - $ref: '#/components/schemas/ErrorResponse' example: detail: >- Reservation not found: booking_2026-09-01_G3F7PA8HO438Z_1787294227662 '409': description: >- Refused by the reservation's current state: already cancelled, already started, inside the venue's change window, nothing can seat the party, or a concurrent change. `detail` says which. content: application/json: schema: $ref: '#/components/schemas/DetailResponse' example: detail: >- This venue stops taking changes 2 hour(s) before a reservation starts '500': $ref: '#/components/responses/ServerError' '501': description: >- A field that is accepted but not applied yet, or a reservation that involves payment. content: application/json: schema: $ref: '#/components/schemas/DetailResponse' example: detail: 'Not implemented yet: notes, tagIds' 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' ReservationId: name: id in: path required: true description: The reservation's `id` — not its `bookingRef`. schema: type: string minLength: 1 example: booking_2026-08-24_G3F7PA8HO438Z_1787294227662 schemas: UpdateReservationRequest: type: object minProperties: 1 description: >- Every field is optional and only what is present is changed, but the body must not be empty. `companyName` and `membershipNumber` are accepted but not applied yet — a patch naming either returns `501`. properties: localBookingDateAndTime: type: string description: >- Venue-local wall clock. A **different date** returns a new reservation — see the description above. example: '2026-09-01T19:00:00' partySize: type: integer minimum: 1 maximum: 1000 description: Re-runs table allocation. sectionId: type: string description: >- Section to move to. Honoured or refused — there is no fallback to another section. serviceId: type: string minLength: 1 description: Service to move to. example: service_dinner tableId: type: string minLength: 1 description: >- Seat the party on this exact table, skipping availability checks. Can produce a double-booked table. example: table_12 firstName: type: string maxLength: 100 description: >- Guest detail. Updates the reservation's copy, not the linked customer record. lastName: type: string maxLength: 200 description: >- Guest detail. Updates the reservation's copy, not the linked customer record. email: type: string format: email maxLength: 250 description: >- Guest detail. Updates the reservation's copy, not the linked customer record. mobileNumber: type: string maxLength: 20 description: >- Guest detail. Updates the reservation's copy, not the linked customer record. companyName: type: string maxLength: 100 description: Accepted but not applied yet — returns `501`. membershipNumber: type: string maxLength: 30 description: Accepted but not applied yet — returns `501`. notes: type: string maxLength: 1000 description: Replaces the reservation's notes. tagIds: type: array maxItems: 20 items: type: string minLength: 1 description: >- Replaces the reservation's tags outright rather than merging into them — send the full set you want to end up with. An empty array clears every tag. selectedOptions: type: array maxItems: 50 items: $ref: '#/components/schemas/SelectedOption' description: >- Replaces the reservation's booking options outright rather than merging into them; an empty array clears every option. **Required, not merely accepted, whenever the rest of the patch invalidates what is stored** — a `partySize` change on a `PerPax` service breaks the rule that main-option quantities total the party, and a `localBookingDateAndTime` or `serviceId` change can resolve a different menu entirely. Omitting it then is a `400`, because the request is incomplete rather than the venue's state refusing it. status: type: string minLength: 1 description: >- The venue's status `id` from the reservation-statuses endpoint — e.g. `status_confirmed`, not the `code`. Several statuses can share one code, so only the id says which you mean. The accepted values are exactly the ids that venue returns; an id it does not have is a `400`. `status_cancelled` is refused here — use the cancel endpoint. example: status_confirmed 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 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. 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. 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: 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.