> ## 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. # List bookings > Lists bookings across the locations the app is granted (or one `location_id`). Two modes: a bounded slot window (`start`/`end`, at most 31 days, default the next 7 days) ordered by slot start, or `updated_since`, which drains bookings updated after an exclusive checkpoint oldest-first so a partner can catch up after downtime. Page with `limit` and the previous page’s `next_cursor` as `starting_after`; `has_more` says whether another page exists. Ties on the ordering timestamp never skip or repeat, and a booking that changes between pages simply re-enters the feed. Take the next `updated_since` checkpoint from the newest `updated_at` you have processed minus a few seconds of overlap and dedupe by `id` + `version`: a booking committed after your drain can carry an `updated_at` set when its transaction began. Locations the bookings surface is not switched on for are omitted (an explicit `location_id` answers 422 `bookings_not_enabled`). Requires `bookings:read`. ## OpenAPI ````yaml /openapi/developer-api.json get /bookings openapi: 3.1.0 info: title: Maple Developer API version: 0.0.1 description: >- Public API for POS and platform partners to integrate with Maple: granted locations and connections, the order loop (validation, notification, accept/deny, status updates), payment-link visibility, menu publishing, and HMAC-signed webhooks. Authenticate every request with a Bearer API key (`mpk_test_…` / `mpk_live_…`). The credential determines the environment: test-mode credentials only see test data, live-mode credentials only see live data. servers: - url: https://api.maple.inc/v1 description: Production - url: https://api.staging.maple.inc/v1 description: Sandbox (development and testing) security: [] tags: - name: General description: Service status and credential introspection. - name: Locations description: The restaurant locations your app has been granted access to. - name: Connections description: Become (or stop being) a granted location’s order receiver. - name: Menu description: Publish and read a connected location’s menu. - name: Delivery zones description: >- Manage a connected location’s delivery zones and check whether a coordinate is deliverable. - name: Orders description: 'The order loop: read orders, submit validation results, and decide orders.' - name: Bookings description: >- Bookings (rolling out per location): a location’s booking profile, availability, holds, bookings, venue verbs, configuration, and live floor. - name: Webhooks description: Event-type catalog, subscriptions, the event ledger, and replay. paths: /bookings: get: tags: - Bookings summary: List bookings description: >- Lists bookings across the locations the app is granted (or one `location_id`). Two modes: a bounded slot window (`start`/`end`, at most 31 days, default the next 7 days) ordered by slot start, or `updated_since`, which drains bookings updated after an exclusive checkpoint oldest-first so a partner can catch up after downtime. Page with `limit` and the previous page’s `next_cursor` as `starting_after`; `has_more` says whether another page exists. Ties on the ordering timestamp never skip or repeat, and a booking that changes between pages simply re-enters the feed. Take the next `updated_since` checkpoint from the newest `updated_at` you have processed minus a few seconds of overlap and dedupe by `id` + `version`: a booking committed after your drain can carry an `updated_at` set when its transaction began. Locations the bookings surface is not switched on for are omitted (an explicit `location_id` answers 422 `bookings_not_enabled`). Requires `bookings:read`. operationId: developer-api-bookings.listBookings parameters: - name: location_id in: query schema: anyOf: - type: string - type: 'null' description: >- Restrict to one granted location. Default: every location the app is granted. required: false - name: start in: query schema: anyOf: - type: string - type: 'null' description: >- ISO-8601 instant. With `end`, lists bookings whose slot starts in [start, end) — at most 31 days. Default window: now to now + 7 days. required: false - name: end in: query schema: anyOf: - type: string - type: 'null' description: ISO-8601 instant, exclusive. Required with `start`. required: false - name: updated_since in: query schema: anyOf: - type: string - type: 'null' description: >- ISO-8601 instant, exclusive checkpoint. Drains bookings updated after it oldest-first — the catch-up path after downtime. Mutually exclusive with `start`/`end`. required: false - name: status in: query schema: anyOf: - type: string enum: - requested - confirmed - seated - completed - declined_by_venue - cancelled_by_guest - cancelled_by_venue - cancelled_unattributed - no_show - type: 'null' required: false - name: starting_after in: query schema: anyOf: - type: string - type: 'null' description: >- The previous page’s `next_cursor` (opaque). Omit for the first page. required: false - name: limit in: query schema: anyOf: - type: string allOf: - pattern: ^[+-]?\d*\.?\d+(?:[Ee][+-]?\d+)?$ - type: 'null' description: Page size, 1–100. Default 20. required: false responses: '200': description: Success content: application/json: schema: type: object properties: object: type: string enum: - list data: type: array items: type: object properties: object: type: string enum: - booking id: type: string description: Opaque, prefixed `bkg_…`. livemode: type: boolean created: anyOf: - anyOf: - type: number - type: string enum: - NaN - type: string enum: - Infinity - type: string enum: - '-Infinity' - type: string enum: - Infinity - '-Infinity' - NaN version: anyOf: - anyOf: - type: number - type: string enum: - NaN - type: string enum: - Infinity - type: string enum: - '-Infinity' - type: string enum: - Infinity - '-Infinity' - NaN location_id: type: string status: type: string enum: - requested - confirmed - seated - completed - declined_by_venue - cancelled_by_guest - cancelled_by_venue - cancelled_unattributed - no_show service_state: anyOf: - type: string enum: - expected - arrived - partially_seated - fully_seated - left - type: 'null' confirmation_code: type: string starts_at: type: string description: ISO-8601 UTC instant. starts_at_local: type: string description: Venue wall-clock, `YYYY-MM-DDTHH:MM`. service_date: type: string description: >- The venue service day the booking belongs to, `YYYY-MM-DD`. duration_minutes: anyOf: - anyOf: - anyOf: - type: number - type: string enum: - NaN - type: string enum: - Infinity - type: string enum: - '-Infinity' - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: >- Turn duration; null on provider-managed bookings, where Maple never invents one. party_size: anyOf: - anyOf: - type: number - type: string enum: - NaN - type: string enum: - Infinity - type: string enum: - '-Infinity' - type: string enum: - Infinity - '-Infinity' - NaN guest: type: object properties: first_name: anyOf: - type: string - type: 'null' last_name: anyOf: - type: string - type: 'null' phone: anyOf: - type: string - type: 'null' description: E.164, when the guest left one. phone_last_four: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' required: - first_name - last_name - phone - phone_last_four - email additionalProperties: false notes: anyOf: - type: string - type: 'null' description: >- The guest-facing note; venue-internal notes are never exposed. channel: type: string description: >- The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`. provider: type: string enum: - maple - opentable - resy - sevenrooms cancellation_policy: anyOf: - type: object properties: type: type: string currency: anyOf: - type: string - type: 'null' description: ISO-4217. policy_text: anyOf: - type: string - type: 'null' tiers: type: array items: type: object properties: within_hours_before_start: anyOf: - anyOf: - type: number - type: string enum: - NaN - type: string enum: - Infinity - type: string enum: - '-Infinity' - type: string enum: - Infinity - '-Infinity' - NaN basis: type: string description: '`per_party` or `per_person`.' amount_cents: anyOf: - anyOf: - anyOf: - type: number - type: string enum: - NaN - type: string enum: - Infinity - type: string enum: - '-Infinity' - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' percent_bps: anyOf: - anyOf: - anyOf: - type: number - type: string enum: - NaN - type: string enum: - Infinity - type: string enum: - '-Infinity' - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: >- Basis points of the party value, when the fee is a percentage. required: - within_hours_before_start - basis - amount_cents - percent_bps additionalProperties: false deposit: anyOf: - type: object properties: amount_cents: anyOf: - anyOf: - type: number - type: string enum: - NaN - type: string enum: - Infinity - type: string enum: - '-Infinity' - type: string enum: - Infinity - '-Infinity' - NaN currency: type: string basis: type: string required: - amount_cents - currency - basis additionalProperties: false - type: 'null' required: - type - currency - policy_text - tiers - deposit additionalProperties: false - type: 'null' updated_at: type: string description: ISO-8601 UTC instant. required: - object - id - livemode - created - version - location_id - status - service_state - confirmation_code - starts_at - starts_at_local - service_date - duration_minutes - party_size - guest - notes - channel - provider - cancellation_policy - updated_at additionalProperties: false has_more: type: boolean next_cursor: anyOf: - type: string - type: 'null' description: >- Opaque cursor for the next page — pass it back as `starting_after`. Null on the last page. It encodes the position observed on this page, so it stays correct even if the last booking changes in between. required: - object - data - has_more - next_cursor additionalProperties: false '400': description: DeveloperApiBadRequest content: application/json: schema: $ref: '#/components/schemas/DeveloperApiBadRequest' '401': description: DeveloperApiUnauthorized content: application/json: schema: $ref: '#/components/schemas/DeveloperApiUnauthorized' '403': description: DeveloperApiForbidden content: application/json: schema: $ref: '#/components/schemas/DeveloperApiForbidden' '404': description: DeveloperApiNotFound content: application/json: schema: $ref: '#/components/schemas/DeveloperApiNotFound' '422': description: DeveloperApiUnprocessable content: application/json: schema: $ref: '#/components/schemas/DeveloperApiUnprocessable' '429': description: DeveloperApiRateLimited content: application/json: schema: $ref: '#/components/schemas/DeveloperApiRateLimited' headers: Retry-After: description: >- Seconds to wait before retrying; also returned as retry_after in the body. schema: type: integer minimum: 1 security: - bearer: [] components: schemas: DeveloperApiBadRequest: type: object properties: _tag: type: string enum: - DeveloperApiBadRequest code: type: string message: type: string required: - _tag - message additionalProperties: false DeveloperApiUnauthorized: type: object properties: _tag: type: string enum: - DeveloperApiUnauthorized message: type: string required: - _tag - message additionalProperties: false DeveloperApiForbidden: type: object properties: _tag: type: string enum: - DeveloperApiForbidden code: type: string enum: - insufficient_scope - wrong_environment message: type: string required: - _tag - code - message additionalProperties: false DeveloperApiNotFound: type: object properties: _tag: type: string enum: - DeveloperApiNotFound message: type: string required: - _tag - message additionalProperties: false DeveloperApiUnprocessable: type: object properties: _tag: type: string enum: - DeveloperApiUnprocessable code: type: string message: type: string details: type: object required: - _tag - code - message additionalProperties: false DeveloperApiRateLimited: type: object properties: _tag: type: string enum: - DeveloperApiRateLimited message: type: string retry_after: anyOf: - type: number - type: string enum: - NaN - type: string enum: - Infinity - type: string enum: - '-Infinity' required: - _tag - message - retry_after additionalProperties: false securitySchemes: bearer: type: http scheme: bearer description: >- API key — `mpk_test_…` for the sandbox, `mpk_live_…` for production. Issued by Maple during partner onboarding. ````