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

# Introduction

> Plug a reservation system into NowOS: floor plan in, reservations in, table lifecycle out.

The NowOS Reservations Provider API connects an external reservation
platform to a NowOS location. The integration is four flows:

1. **Read the floor plan** — published rooms and tables, each with a
   stable UUID. Store that UUID on your side (EatNow keeps it in
   `pos_table_id`); it is the only table reference the API accepts.
2. **Write reservations** — create and update reservations keyed by
   *your own* ids, each carrying its guest (name, contact, a guest-facing
   `allergies` note and a staff-only, two-way `internalNote`). A party you
   seat yourself with nobody to name sends `partyName: null` — the till
   shows its own "Walk-in", so never invent a placeholder. Setting a
   reservation to `seated` with tables is an instruction: the till opens
   the order on the floor plan. See
   [Reservation lifecycle](/api-reference/lifecycle).
3. **Consume webhooks** — signed events for everything that happens on
   the floor: parties seated, spend sent to the kitchen, checks paid,
   tables freed.
4. **Feed the guest profile back** — `check.paid` tells you what each
   party spent; you keep the CRM, aggregate it, and return those
   aggregates on the reservation so staff see a 360° guest profile on the
   till. NowOS never recomputes them — one writer per field. See
   [Guest profile & CRM](/api-reference/lifecycle#guest-profile-and-crm).

The integration point is always the NowOS cloud. You never talk to
in-store devices, and a provider outage never blocks the restaurant.

## Authentication

Every request carries a location-scoped Bearer key:

```http theme={null}
Authorization: Bearer nowos_sk_live_…
```

One key per location, issued at registration together with your webhook
signing secret. The key identifies the location, so URLs carry no
location id. Keys can be rotated (the old key dies immediately) and
revoked.

## Errors

Every error body has one shape:

```json theme={null}
{ "error": { "code": "table_occupied", "message": "…", "occupiedBy": { "orderId": "…", "reservationExternalId": null } } }
```

Branch on `code` only — messages are free text. Codes: `unauthorized`,
`unknown_reservation`, `duplicate_reservation`, `unknown_table_id`,
`table_occupied`, `floorplan_not_published`, `draft_not_empty`,
`validation_failed`. `occupiedBy` is present on `table_occupied` only.

A **stale** update is *not* an error: `PUT` acknowledges it with
`200 { "outcome": "stale" }` and changes nothing, so you can retry any
write blindly.

## Idempotency and ordering

* Reservations are keyed by your `externalId`; re-sending the same body
  is a no-op.
* Every write carries your `updatedAt`. NowOS applies last-write-wins on
  it: a delivery that arrives late can never regress newer state.
* Webhook envelopes carry an `id` (your idempotency key) and a
  per-location monotonic `sequence`. Delivery order is **not**
  guaranteed — drop what you have already applied.