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.
Scope & access
Requires a valid owner session and ownership of businessId. Customer booking tokens do not authorize this operation.
This tool advertises idempotent behavior. If an idempotencyKey is specified, reuse it with identical arguments only when retrying that same intended action.
Parameters
These are the directory endpoint parameters. Business endpoints scope public discovery to the published business; owner calls still require businessId. Inspect tools/list on your endpoint for the exact schema.
businessIdRequiredPublished 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.
statusesOptionalOptional booking statuses to include.
channelOptionalOptional acquisition channel filter.
fromOptionalISO 8601 timestamp including timezone offset, e.g. 2026-11-14T00:00:00+05:30.
toOptionalISO 8601 timestamp including timezone offset, e.g. 2026-11-14T00:00:00+05:30.
qOptionalSearch booking ID or customer/guest name.
limitOptionalMaximum rows, 1–200, newest booking starts first.
Example call
Pass this object to the MCP client's callTool method. Replace placeholders with returned IDs, saved credentials and the customer's details; use future dates appropriate to their request.
{
"name": "list_bookings",
"arguments": {
"businessId": "<businessId>"
}
}JSON schemas
Nested fields, formats, enums and constraints are included in the complete schemas. Successful data is returned in structuredContent. SDK input validation and domain errors use different error shapes.
Input schemaJSON Schema
{
"$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 schemaJSON Schema
{
"$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
}Behavior annotationsMCP
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors & next steps
Check isError before reading a success response. Follow nextStep where supplied, and never treat a pending booking as confirmed. See Errors and retries and the booking lifecycle for recovery paths.
Back to all tools