Configure bookings

​

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.

​

Publish a configuration

{
  "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."
  }
}

​

Publish without overwriting the venue

{ "...": "the whole configuration", "expected_revision": "<revision from your last read>" }

​

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.
• Every area is bookable. Availability tries the first area in areas, then the others in poolId order (the order a read returns them), and seats the party in the first one with a free table or combination that fits; a booking stays in the area it was seated in. Shifts and closed dates apply to the whole location.
• 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.

​

Blackout dates

PUT /v1/locations/{locationId}/booking_blackouts

{
  "blackout_dates": [
    { "start_date": "2026-12-24", "end_date": "2026-12-26", "reason": "Holidays" },
    { "start_date": "2026-10-10", "end_date": "2026-10-10", "start_time": "18:00", "end_time": "22:00" }
  ],
  "expected_revision": "<blackout_dates_revision from the booking profile>"
}

• The body is the whole list: ranges you leave out are removed, and [] clears them all. The venue edits the same list in its dashboard, so read blackout_dates and blackout_dates_revision from the profile, edit, and send that revision as expected_revision. If the list changed since you read it, the write answers 409 stale_blackout_dates and nothing changes: read it again and reapply your edit. Without expected_revision the write replaces whatever is there.
• Dates are venue-local and inclusive. A range without times blocks whole days; start_time applies to the first day and end_time to the last. At most 100 ranges, with notes of up to 200 characters.
• Invalid ranges (a date that doesn’t exist, an end before the start, a malformed time) answer 400 invalid_blackout_dates and change nothing.
• Availability omits slots inside a blackout; native locations also withhold seatings that would run into one. A quote taken before a blackout was added is refused when held or booked: 409 slot_unavailable at native locations, 422 date_blocked at provider-managed ones. Existing bookings inside a new blackout are not cancelled, and neither is a provider-managed booking already in flight when the blackout is saved.
• A blackout stops reservations, not the host stand: walk-ins (POST /v1/locations/{locationId}/walk_ins) and seating waitlist parties still work inside one, on normal table availability.
• At a provider-managed location, the provider’s own channels (such as OpenTable’s website) don’t see Maple’s list; the venue blocks the dates there too.

​

Provision a booking sandbox