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

# Configure bookings

> Publish native booking areas, tables, shifts, turn times, pacing, and policies without replacing the menu.

A native location's booking configuration describes its seating areas and booking rules. Publish the complete document to `POST /v1/locations/{locationId}/booking_configuration`; read it with `GET` on the same path.

## Prerequisites

* Your app is granted the location.
* Publishing requires `bookings:configure`; reading requires `bookings:read`.
* Maple has enabled the location's `bookings-public-api` rollout flag.
* The location has a Maple-native connection, or no booking connection yet. Provider-managed locations answer `422 capability_unsupported`.

Publishing configuration does **not** enable bookings. Maple or the merchant must enable the native connection and the `bookings-native-engine` flag separately. Check `booking_profile.enabled` before offering availability.

## Publish a configuration

Configuration bodies use camelCase, like menu documents. `poolId` and `unitId` are your stable identifiers. Unit IDs must be unique across the document.

```json theme={null}
{
  "timeZone": "America/New_York",
  "currency": "USD",
  "areas": [
    {
      "poolId": "dining",
      "name": "Dining Room",
      "kind": "seat",
      "units": [
        { "unitId": "t1", "seats": { "min": 1, "max": 2 } },
        { "unitId": "t2", "seats": { "min": 1, "max": 4 }, "tags": ["window"] }
      ],
      "combinations": [
        { "unitIds": ["t1", "t2"], "seats": { "min": 3, "max": 6 } }
      ]
    }
  ],
  "turnBands": [
    { "minGuests": 1, "maxGuests": 2, "minutes": 90 },
    { "minGuests": 3, "maxGuests": 6, "minutes": 120 }
  ],
  "shifts": [
    { "day": "FRI", "start": "17:00", "end": "23:00" },
    { "day": "SAT", "start": "12:00", "end": "23:00" }
  ],
  "pacing": { "intervalMinutes": 15, "maxCovers": 12, "enforcement": "hard" },
  "bookingPolicy": {
    "minLeadMinutes": 60,
    "maxHorizonDays": 60,
    "slotAlignment": "quarter_hourly",
    "autoConfirm": true
  },
  "cancellationPolicy": {
    "requiresCardOnFile": false,
    "tiers": [],
    "rescheduleCutoffHours": 2,
    "policyText": "Please contact the venue for late changes."
  }
}
```

The response contains the normalized configuration plus `object: "booking_configuration"`, `location_id`, `version_id`, `published_at`, and `livemode`. Reads materialize policy defaults; they need not reproduce omitted fields byte for byte.

## Publication rules

* The document replaces the store's authored booking configuration, not its menu or unrelated catalog resources and policies. Subsequent provider/menu publishes preserve that booking configuration too.
* Re-publishing an identical configuration does not create another version. There is no `idempotency_key` field for configuration.
* Changed turn times or policies take effect for new availability quotes. Existing bookings retain their pinned terms.
* The currency must match an existing catalog's currency. A first configuration establishes the currency when no catalog exists.
* Times are venue-local `HH:MM`; a shift's end must be after its start. Split overnight opening hours across days.
* Turn bands must be ordered and non-overlapping. Combinations must name distinct units from their own area.
* Unknown fields, invalid zones/dates, and invalid bounds are rejected. `400` validation responses identify the invalid input. `422 configuration_rejected` means the document cannot be applied to the catalog.
* A read before configuration exists answers `404`.

<Note>
  The live floor includes authored seating areas, but native availability currently allocates against the engine's primary area. Publishing additional areas does not yet enable multi-area slot allocation. Card-on-file/deposit booking flows and charging cancellation fees are separate capabilities; declaring a policy is not a payment integration.
</Note>

## Provision a booking sandbox

In Maple's admin portal, select **Native bookings + sample floor** when provisioning the partner sandbox. The option defaults off. It creates an enabled Maple booking connection and, if configuration is absent, seeds four tables, 90-minute turns, and daily opening hours. Re-running it preserves an existing configuration and refuses to replace an OpenTable connection.

The staging provisioning CLI exposes the same option as `--booking-connection`. For a booking-only partner, you can skip the POS connection; a location grant is sufficient for bookings. Existing keys that lack booking scopes need a newly minted key.

The provisioning result's `bookings_configured` confirms that the step ran, not that rollout is enabled. Maple must target the sandbox location in the staging PostHog project for **both** `bookings-native-engine` and `bookings-public-api`. Then run [search → hold → create → cancel](/developer-api/guides/take-bookings) using the sandbox credential.