Bookings

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. To find the booking a guest is calling about, pass location_id with phone and/or confirmation_code: without a window this matches bookings at any time, ordered by slot start; add start/end to narrow it. At a provider-managed location a lookup with phone first checks the provider, so a reservation made directly there is found; a code-only lookup covers the reservations Maple already knows about. A lookup without location_id answers 400 location_required, an unusable phone 400 invalid_phone. Locations the bookings surface is not switched on for are omitted (an explicit location_id answers 422 bookings_not_enabled). Requires bookings:read.

List bookings

curl --request GET \
  --url https://api.maple.inc/v1/bookings \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.maple.inc/v1/bookings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.maple.inc/v1/bookings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.maple.inc/v1/bookings"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.maple.inc/v1/bookings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "data": [
    {
      "object": "booking",
      "id": "<string>",
      "livemode": true,
      "created": 123,
      "version": 123,
      "location_id": "<string>",
      "status": "requested",
      "service_state": "expected",
      "confirmation_code": "<string>",
      "starts_at": "<string>",
      "starts_at_local": "<string>",
      "service_date": "<string>",
      "duration_minutes": 123,
      "party_size": 123,
      "guest": {
        "first_name": "<string>",
        "last_name": "<string>",
        "phone": "<string>",
        "phone_last_four": "<string>",
        "email": "<string>"
      },
      "notes": "<string>",
      "channel": "<string>",
      "provider": "maple",
      "cancellation_policy": {
        "type": "<string>",
        "currency": "<string>",
        "policy_text": "<string>",
        "tiers": [
          {
            "within_hours_before_start": 123,
            "basis": "<string>",
            "amount_cents": 123,
            "percent_bps": 123
          }
        ],
        "deposit": {
          "amount_cents": 123,
          "currency": "<string>",
          "basis": "<string>"
        }
      },
      "experience": {
        "id": "<string>",
        "name": "<string>"
      },
      "updated_at": "<string>"
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}

{
  "_tag": "DeveloperApiBadRequest",
  "message": "<string>",
  "feedback": "<string>",
  "code": "<string>"
}

{
  "_tag": "DeveloperApiUnauthorized",
  "message": "<string>",
  "feedback": "<string>"
}

{
  "_tag": "DeveloperApiForbidden",
  "code": "insufficient_scope",
  "message": "<string>",
  "feedback": "<string>"
}

{
  "_tag": "DeveloperApiNotFound",
  "message": "<string>",
  "feedback": "<string>"
}

{
  "_tag": "DeveloperApiUnprocessable",
  "code": "<string>",
  "message": "<string>",
  "feedback": "<string>",
  "details": {}
}

{
  "_tag": "DeveloperApiRateLimited",
  "message": "<string>",
  "retry_after": 123,
  "feedback": "<string>"
}

Authorizations

Authorization

string

header

required

API key — mpk_test_… for the sandbox, mpk_live_… for production. Issued by Maple during partner onboarding.

Query Parameters

location_id

string | null

Restrict to one granted location. Default: every location the app is granted.

start

string | null

ISO-8601 instant. With end, lists bookings whose slot starts in [start, end) — at most 31 days. Default window: now to now + 7 days.

end

string | null

ISO-8601 instant, exclusive. Required with start.

updated_since

string | null

ISO-8601 instant, exclusive checkpoint. Drains bookings updated after it oldest-first — the catch-up path after downtime. Mutually exclusive with start/end.

status

enum<string> | null

Available options:

requested,

confirmed,

seated,

completed,

declined_by_venue,

cancelled_by_guest,

cancelled_by_venue,

cancelled_unattributed,

no_show

phone

string | null

Find a guest’s bookings by the phone on the booking. E.164, or a US number without +1 and with any formatting; it is normalized before matching. Requires location_id. Without a window, matches bookings at any time.

confirmation_code

string | null

Find a booking by the confirmation_code the guest was given, exactly as the booking shows it. Requires location_id. Without a window, matches bookings at any time.

Required string length: 1 - 64

starting_after

string | null

The previous page’s next_cursor (opaque). Omit for the first page.

limit

string | null

Page size, 1–100. Default 20.

Pattern: ^[+-]?\d*\.?\d+(?:[Ee][+-]?\d+)?$

Response

Success

object

enum<string>

required

Available options:

list

data

object[]

required

Show child attributes

has_more

boolean

required

next_cursor

string | null

required

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.

⌘I

List bookings

curl --request GET \
  --url https://api.maple.inc/v1/bookings \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.maple.inc/v1/bookings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.maple.inc/v1/bookings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.maple.inc/v1/bookings"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.maple.inc/v1/bookings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "data": [
    {
      "object": "booking",
      "id": "<string>",
      "livemode": true,
      "created": 123,
      "version": 123,
      "location_id": "<string>",
      "status": "requested",
      "service_state": "expected",
      "confirmation_code": "<string>",
      "starts_at": "<string>",
      "starts_at_local": "<string>",
      "service_date": "<string>",
      "duration_minutes": 123,
      "party_size": 123,
      "guest": {
        "first_name": "<string>",
        "last_name": "<string>",
        "phone": "<string>",
        "phone_last_four": "<string>",
        "email": "<string>"
      },
      "notes": "<string>",
      "channel": "<string>",
      "provider": "maple",
      "cancellation_policy": {
        "type": "<string>",
        "currency": "<string>",
        "policy_text": "<string>",
        "tiers": [
          {
            "within_hours_before_start": 123,
            "basis": "<string>",
            "amount_cents": 123,
            "percent_bps": 123
          }
        ],
        "deposit": {
          "amount_cents": 123,
          "currency": "<string>",
          "basis": "<string>"
        }
      },
      "experience": {
        "id": "<string>",
        "name": "<string>"
      },
      "updated_at": "<string>"
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}

{
  "_tag": "DeveloperApiBadRequest",
  "message": "<string>",
  "feedback": "<string>",
  "code": "<string>"
}

{
  "_tag": "DeveloperApiUnauthorized",
  "message": "<string>",
  "feedback": "<string>"
}

{
  "_tag": "DeveloperApiForbidden",
  "code": "insufficient_scope",
  "message": "<string>",
  "feedback": "<string>"
}

{
  "_tag": "DeveloperApiNotFound",
  "message": "<string>",
  "feedback": "<string>"
}

{
  "_tag": "DeveloperApiUnprocessable",
  "code": "<string>",
  "message": "<string>",
  "feedback": "<string>",
  "details": {}
}

{
  "_tag": "DeveloperApiRateLimited",
  "message": "<string>",
  "retry_after": 123,
  "feedback": "<string>"
}

Get started

Orders

Menus

Delivery

Bookings

Core concepts

Tutorials

API reference

Endpoints

Resources

List bookings

Authorizations

Query Parameters

Response