# create_hold

Temporarily reserves one option (by optionId, or the first available option for params) for a few minutes so the customer can confirm. Returns holdId, expiresAt, the quote and the next step. Does not charge or message the customer.

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

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

## Parameters

- **businessId** (string; required): businessId: a business ID from search_businesses, e.g. "biz_01j…", or the business's booking-page slug, e.g. "studio-nine"
- **optionId** (string; optional): optionId: an option ID returned by check_availability, e.g. "opt_eyJ…"
- **offeringId** (string; optional): offeringId: an offering ID from list_offerings or get_business, e.g. "off_01j…"
- **params** (object; required): params: booking parameters matching the business's bookingParamsSchema from get_business
- **customer** (object; required): customer: who the hold is for; phone/email are optional at this step
- **idempotencyKey** (string; required): idempotencyKey: a unique string you generate per intended action (e.g. a UUID); retries with the same key return the same result

## Example MCP call

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

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

## Input JSON Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string",
      "minLength": 1,
      "description": "businessId: a business ID from search_businesses, e.g. \"biz_01j…\", or the business's booking-page slug, e.g. \"studio-nine\""
    },
    "optionId": {
      "type": "string",
      "minLength": 1,
      "description": "optionId: an option ID returned by check_availability, e.g. \"opt_eyJ…\""
    },
    "offeringId": {
      "type": "string",
      "minLength": 1,
      "description": "offeringId: an offering ID from list_offerings or get_business, e.g. \"off_01j…\""
    },
    "params": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "params: booking parameters matching the business's bookingParamsSchema from get_business"
    },
    "customer": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "name: customer full name, e.g. \"Asha Perera\""
        },
        "phone": {
          "type": "string",
          "pattern": "^\\+[1-9]\\d{6,14}$",
          "description": "phone: customer mobile number in E.164 format, e.g. \"+94771234567\""
        },
        "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": "email: customer email address, e.g. \"asha@example.com\""
        }
      },
      "required": [
        "name"
      ],
      "description": "customer: who the hold is for; phone/email are optional at this step"
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 8,
      "maxLength": 200,
      "description": "idempotencyKey: a unique string you generate per intended action (e.g. a UUID); retries with the same key return the same result"
    }
  },
  "required": [
    "businessId",
    "params",
    "customer",
    "idempotencyKey"
  ]
}
```

## Output JSON Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "holdId": {
      "type": "string"
    },
    "holdToken": {
      "type": "string",
      "description": "Secret for get_booking_progress, release_hold and resend_verification_code. Store securely."
    },
    "status": {
      "type": "string",
      "const": "held"
    },
    "expiresAt": {
      "type": "string"
    },
    "nextStep": {
      "type": "string"
    }
  },
  "required": [
    "holdId",
    "holdToken",
    "status",
    "expiresAt",
    "nextStep"
  ],
  "additionalProperties": {}
}
```

## Annotations

```json
{
  "readOnlyHint": false,
  "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.