# list_bookings

OWNER ONLY. List this owner's business bookings, optionally filtered by status, channel, customer name, booking ID or time window. Requires owner authentication. Returns parent bookings; from/to select overlapping stays or appointments.

Canonical: https://bookwise.live/docs/tools/list_bookings

Version: 1.1.0
Scope: Directory + business
Authentication: Owner session
Category: Owner operations

## Parameters

- **businessId** (string; required): Published business ID from search_businesses, or the business's booking-page slug (e.g. "studio-nine"); owner calls may also use the business ID shown in the dashboard.
- **statuses** (array<"held" | "pending_verification" | "pending_payment" | "pending_approval" | "confirmed" | "cancelled" | "expired" | "no_show" | "completed">; optional): Optional booking statuses to include.
- **channel** ("mcp_directory" | "mcp_business" | "chatgpt_app" | "booking_page" | "owner_manual" | "api"; optional): Optional acquisition channel filter.
- **from** (string; optional): ISO 8601 timestamp including timezone offset, e.g. 2026-11-14T00:00:00+05:30.
- **to** (string; optional): ISO 8601 timestamp including timezone offset, e.g. 2026-11-14T00:00:00+05:30.
- **q** (string; optional): Search booking ID or customer/guest name.
- **limit** (integer; optional): Maximum rows, 1–200, newest booking starts first.

## Example MCP call

Replace placeholders with returned IDs and saved credentials. Example dates must be replaced with the customer's future dates.

```json
{
  "name": "list_bookings",
  "arguments": {
    "businessId": "<businessId>"
  }
}
```

## Input JSON Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string",
      "minLength": 1,
      "description": "Published business ID from search_businesses, or the business's booking-page slug (e.g. \"studio-nine\"); owner calls may also use the business ID shown in the dashboard."
    },
    "statuses": {
      "description": "Optional booking statuses to include.",
      "maxItems": 9,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "held",
          "pending_verification",
          "pending_payment",
          "pending_approval",
          "confirmed",
          "cancelled",
          "expired",
          "no_show",
          "completed"
        ]
      }
    },
    "channel": {
      "description": "Optional acquisition channel filter.",
      "type": "string",
      "enum": [
        "mcp_directory",
        "mcp_business",
        "chatgpt_app",
        "booking_page",
        "owner_manual",
        "api"
      ]
    },
    "from": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      "description": "ISO 8601 timestamp including timezone offset, e.g. 2026-11-14T00:00:00+05:30."
    },
    "to": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      "description": "ISO 8601 timestamp including timezone offset, e.g. 2026-11-14T00:00:00+05:30."
    },
    "q": {
      "description": "Search booking ID or customer/guest name.",
      "type": "string",
      "maxLength": 200
    },
    "limit": {
      "default": 50,
      "description": "Maximum rows, 1–200, newest booking starts first.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "required": [
    "businessId"
  ]
}
```

## Output JSON Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "bookings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "bookingId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "held",
              "pending_verification",
              "pending_payment",
              "pending_approval",
              "confirmed",
              "cancelled",
              "expired",
              "no_show",
              "completed"
            ]
          },
          "start": {
            "type": "string"
          },
          "end": {
            "type": "string"
          },
          "offeringName": {
            "type": [
              "string",
              "null"
            ]
          },
          "guestName": {
            "type": [
              "string",
              "null"
            ]
          },
          "total": {
            "type": "object",
            "properties": {
              "amountMinor": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "currency": {
                "type": "string"
              },
              "formatted": {
                "type": "string"
              }
            },
            "required": [
              "amountMinor",
              "currency",
              "formatted"
            ],
            "additionalProperties": false
          },
          "channel": {
            "type": "string"
          }
        },
        "required": [
          "bookingId",
          "status",
          "start",
          "end",
          "offeringName",
          "guestName",
          "total",
          "channel"
        ],
        "additionalProperties": false
      }
    },
    "limit": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "bookings",
    "limit"
  ],
  "additionalProperties": false
}
```

## Annotations

```json
{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false
}
```

On failure, inspect isError and content; domain errors may include structuredContent.code, retryable, details.fields or alternatives. Annotations are behavior hints, not authorization.