Bookd

Find independent stays bookable direct on Bookd (hotels, B&Bs, guesthouses, apartments, houses, villas, cabins) for a location and dates. Read-only: nothing is booked or held. Bookd properties come first: only properties with a room or unit free for every night are returned, cheapest first (exact town matches first), paginated. Each result has nightly price, total_price (incl. any cleaning fee and taxes), cancellation policy, bedrooms/bathrooms/beds for whole homes, any information-only damage deposit held by the property, and any deposit due (only when the property takes card deposits; otherwise the guest pays the property directly). If no Bookd property matches a location, the result has partner_results instead: links to partner hotels (accommodation only) on Trip.com and a Stay22 map for that place, dates and guests, with min_price, max_price, stars and currency applied. Partner hotels are not Bookd properties: the guest books and pays on Trip.com or the partner site, under that site's terms, and Bookd may earn a commission. Never call request_booking for them. Finding the partner city sends only the location text to Trip.com.

{
  "type": "object",
  "properties": {
    "location": {
      "description": "Town, county/state or country, e.g. \"Doolin\", \"County Clare\", \"Ireland\", \"UK\", \"North Carolina\", \"United States\". Empty = everywhere.",
      "type": "string",
      "maxLength": 100
    },
    "check_in": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD"
    },
    "check_out": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD"
    },
    "guests": {
      "default": 2,
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "min_price": {
      "description": "Min price per room or unit per night. Bookd properties: in the property currency. Partner hotel links: in currency.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000
    },
    "max_price": {
      "description": "Max price per room or unit per night. Bookd properties: in the property currency. Partner hotel links: in currency.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000
    },
    "stars": {
      "description": "Minimum star rating (3, 4 or 5) for partner hotel links. Bookd properties have no star rating and are never hidden by it.",
      "type": "integer",
      "minimum": 3,
      "maximum": 5
    },
    "currency": {
      "description": "Currency for partner hotel links and their price filter. Default: local currency of the place (EUR in the euro area, GBP in the UK, else USD).",
      "type": "string",
      "enum": [
        "USD",
        "EUR",
        "GBP"
      ]
    },
    "property_type": {
      "description": "Filter by type: hotel, bnb, guesthouse, inn, hostel, motel, lodge, apartment, condo, house, villa, cabin, cottage, chalet, other (\"B&B\" and \"vacation rental\" are understood)",
      "anyOf": [
        {
          "type": "string",
          "maxLength": 40
        },
        {
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 40
          }
        }
      ]
    },
    "whole_home": {
      "description": "true = only whole homes (apartment, condo, house, villa, cabin, cottage, chalet)",
      "type": "boolean"
    },
    "min_bedrooms": {
      "type": "integer",
      "minimum": 0,
      "maximum": 50
    },
    "min_bathrooms": {
      "type": "number",
      "minimum": 0,
      "maximum": 50
    },
    "min_beds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100
    },
    "page": {
      "default": 1,
      "description": "Results page (see has_more / next_page)",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "limit": {
      "default": 10,
      "description": "Results per page",
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    }
  },
  "required": [
    "check_in",
    "check_out"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read-only. Full details of one Bookd property by its slug (from search_stays or a Bookd link): type, description, photos, amenities, house rules, check-in/out times, rooms or units (bedrooms, bathrooms, beds, cleaning fee) and prices from, taxes, cancellation policy and any damage deposit (held by the property).

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "pattern": "^[a-z0-9-]{2,60}$",
      "description": "Property slug, e.g. \"seaview-house-doolin\""
    }
  },
  "required": [
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read-only. Live availability for one Bookd property and dates (re-reads the owner's calendars first; nothing is booked or held), with room/unit prices, totals including any cleaning fee and taxes, cancellation policy and any deposit due.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "pattern": "^[a-z0-9-]{2,60}$",
      "description": "Property slug, e.g. \"seaview-house-doolin\""
    },
    "check_in": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD"
    },
    "check_out": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD"
    },
    "guests": {
      "default": 1,
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "slug",
    "check_in",
    "check_out"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Send a booking request to the property (hotel, B&B, guesthouse or vacation rental) for a room or unit and dates. The resulting stay contract is directly between the guest and the property; Bookd is only the booking platform. Only call after the guest has confirmed the room, dates, guests, and given their name and email. Returns a booking_id and, when online payments are on, a payment_url for the deposit (card held, charged only if the owner accepts). Usually status is "requested": the request is emailed to the property (the guest is emailed when it answers) and the room is held until the owner answers or the request expires. Instant booking: for properties with instant_booking=true, Bookd checks the room live in the property's own booking system; if it is available, the booking is made there at once and status is "confirmed" (with the booking_id; the guest and property are emailed). With a deposit, the reply has instant_booking=true and a payment_url, and the booking is confirmed as soon as the deposit is paid (check booking_status). If the live check or write fails it stays a normal request; if the room was just taken, an error says nothing was booked. Only tell the guest it is confirmed when status is "confirmed". Not idempotent: each call creates a new request, so do not retry after a booking_id is returned (use booking_status). The guest pays the property directly; Bookd never handles guest money.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "pattern": "^[a-z0-9-]{2,60}$",
      "description": "Property slug, e.g. \"seaview-house-doolin\""
    },
    "room": {
      "description": "Room name from check_availability; omit for the cheapest free room",
      "type": "string",
      "maxLength": 100
    },
    "check_in": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD"
    },
    "check_out": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD"
    },
    "guests": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "guest_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "guest_email": {
      "type": "string",
      "maxLength": 200,
      "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,}$"
    },
    "guest_phone": {
      "type": "string",
      "maxLength": 40
    },
    "message": {
      "description": "Note for the owner, e.g. arrival time",
      "type": "string",
      "maxLength": 1000
    },
    "creator_code": {
      "description": "Optional: a creator or promo code the guest mentions (e.g. from a video). Only pass one the guest gave you; never invent or suggest one.",
      "type": "string",
      "maxLength": 40
    }
  },
  "required": [
    "slug",
    "check_in",
    "check_out",
    "guests",
    "guest_name",
    "guest_email"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read-only. Status of a Bookd booking by its booking_id (e.g. BKD-AB12CD3): requested, accepted (= confirmed, including instant bookings), declined, expired or cancelled, with dates, room and price. Returns no guest personal data.

{
  "type": "object",
  "properties": {
    "booking_id": {
      "type": "string",
      "maxLength": 20
    }
  },
  "required": [
    "booking_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Cancel a Bookd booking for the guest. First call with confirm=false to see the refund under the property's policy and tell the guest; only call with confirm=true after the guest explicitly agrees. Needs the booking_id and the email used to book. confirm=false changes nothing. confirm=true cancels for good (it cannot be undone): it releases any card hold or refunds under the policy on the property's own Stripe account, frees the dates (and cancels it in the property's booking system when it is connected), and emails the property and the guest.

{
  "type": "object",
  "properties": {
    "booking_id": {
      "type": "string",
      "maxLength": 20
    },
    "guest_email": {
      "type": "string",
      "maxLength": 200,
      "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,}$"
    },
    "confirm": {
      "default": false,
      "type": "boolean"
    }
  },
  "required": [
    "booking_id",
    "guest_email"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}