Skip to main content
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.
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.
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.

​
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 using the sandbox credential.