# join_booking_waitlist

Subscribe the customer to one email when their requested option becomes available. Requires explicit customer intent to receive the alert. Does not reserve, pay, or auto-book. The entry expires after the requested local date. Separate from the business signup waitlist.

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

Version: 1.1.0
Scope: Directory + business
Authentication: As specified in parameters
Category: Booking management

## Parameters

- **offeringId** (string; optional): Offering ID from list_offerings, belonging to this business.
- **params** (object; required): Booking parameters from get_business.bookingParamsSchema. Hotel: checkIn/checkOut YYYY-MM-DD, adults. Restaurant: date, time HH:mm, partySize. Salon: offeringId, date, optional time/staffId. Dates and times use the business timezone.
- **name** (string; required): Customer name for the availability notification.
- **email** (string; required): Customer email address for one requested availability notification; does not grant marketing consent.
- **idempotencyKey** (string; required): Generate a UUID per intended mutation. Reuse the same key and identical parameters only when retrying that action.
- **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.

## Example MCP call

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

```json
{
  "name": "join_booking_waitlist",
  "arguments": {
    "params": {
      "checkIn": "2026-11-14",
      "checkOut": "2026-11-16",
      "adults": 2
    },
    "name": "Asha Perera",
    "email": "asha@example.com",
    "idempotencyKey": "<new-UUID-for-this-action>",
    "businessId": "<businessId>"
  }
}
```

## Input JSON Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "offeringId": {
      "type": "string",
      "minLength": 1,
      "description": "Offering ID from list_offerings, belonging to this business."
    },
    "params": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Booking parameters from get_business.bookingParamsSchema. Hotel: checkIn/checkOut YYYY-MM-DD, adults. Restaurant: date, time HH:mm, partySize. Salon: offeringId, date, optional time/staffId. Dates and times use the business timezone."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Customer name for the availability notification."
    },
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "Customer email address for one requested availability notification; does not grant marketing consent."
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 8,
      "maxLength": 200,
      "description": "Generate a UUID per intended mutation. Reuse the same key and identical parameters only when retrying that action."
    },
    "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."
    }
  },
  "required": [
    "params",
    "name",
    "email",
    "idempotencyKey",
    "businessId"
  ]
}
```

## Output JSON Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "waitlistId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "const": "waiting"
    },
    "expiresAt": {
      "type": "string"
    },
    "currentlyAvailable": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "waitlistId",
    "status",
    "expiresAt",
    "currentlyAvailable",
    "message"
  ],
  "additionalProperties": false
}
```

## Annotations

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

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