Skip to main content

Changelog

All notable changes to the Booking Brain Developer API are documented here.

Admin API — 2026-09-24​

Refunds and LTD payments: which account pays, and a full record of payments to owners. Every guest refund now records whether the client account (Monzo, via the Monday pay run) or The Best of Exmoor LTD (Revolut) pays it. Owners can now be paid from the same ledger (for example, goodwill), and those payments are always LTD-funded. Goes live with bb_app_api #4119 + #4125. Full details are in the admin reference (Admin Data API → Guest refunds & LTD payments).

Added​

  • POST /admin-data/ltd-payments records a payment LTD has already sent from Revolut (guest or owner). It is created already paid, idempotent on the Revolut transaction id, and never in a Monzo bank file. New scope ltd_payment:record (critical, account holder only).
  • GET /admin-data/ltd-payments?user_id= lists a person's refunds and LTD payments, masked. Scope guest_refund:read.
  • Revolut payout worker routes (revolut-queue, revolut-drafted, revolut-draft-failed, revolut-paid) with the new scope guest_refund:revolut_payout (critical, account holder only). The server never holds Revolut credentials.

Documentation corrections — 2026-08-07​

Three errors in these docs meant an integration built by following them exactly could not make a successful call. All are now fixed:

Fixed​

  • Base URL corrected to /api/v1/developer. Earlier versions of these docs showed https://app.bookingbrain.com/api/v2/developer, which returns 404. There is no v2 — the working base URL is https://app.bookingbrain.com/api/v1/developer.
  • Public sandbox key removed. The previously published sandbox key (bb_sandbox_test_key...) was never provisioned and always returned 403. There is no sandbox key or sandbox mode: all keys are issued per-client by the Booking Brain team (see Authentication) and operate against live data, including real bookings and payments.
  • Search parameters corrected. The search endpoint rejects unknown parameters with a 422. Search examples previously used place, nights, pets, bedrooms, and sort, none of which exist on that endpoint (GET /developer/places/{slug} does accept nights). The correct names are property_place_slug, booking_nights, no_of_dogs, min_bed_rooms, and sort_by — see the API Reference for the full accepted list.
  • Example data corrected. Example property IDs and place slugs now reference real records (place slugs use the stay-in-* form, e.g. stay-in-exmoor); the previous examples (property 312, place exmoor) did not exist.

Admin API — 2026-06-22​

Admin-key READS that retire the DB tunnel for the property-closeout check. A property's security (damage) deposit, its assigned cancellation policy, and its discount levers / linked occupancy-group(s) can now be read over the API with an admin API key (or an admin/owner JWT) — no more dropping to the read-only database tunnel to confirm them. Each is read-only and ownership-guarded; the GET-before-write hard rules apply to the writes, not these reads. Ship with bb_app_api #1391 / #1392 / #1393 (#1382–#1386).

Added​

  • GET /properties/{id}/security-deposit — the refundable security/damage deposit + on/off flag ({ property_id, security_deposit, disable_security }). The read counterpart of PATCH /properties/{id}/security-deposit, and distinct from the payment deposit (GET /properties/{id}/deposit). Scope property.pricing:read. (#1382)
  • GET /properties/{id}/cancellation-policy — the property's assigned cancellation policy resolved against the public catalogue ({ cancellation_policy_ref_id, policy_title, owner_policy_description }). Distinct from bookings.cancellation-policy:read (the per-booking policy + cover) — this is the per-property assignment. New scope property.cancellation-policy:read. (#1383)
  • GET /properties/{id}/discounts/occupancy-groups — the shared occupancy-discount group(s) a property is linked to (the reverse lookup, complementing GET /occupancy-discounts/{id}). PII-free — the staff/owner name is stripped on the admin-API-key path. Scope property.pricing:read. (#1384)
  • GET /properties/{id}/discounts/low-occupancy and GET /properties/{id}/discounts/short-break-rules are now admin-API-key readable (were JWT-only). Scope property.pricing:read. (#1385)

Changed​

  • GET /properties/{id}/segment-pricing now also returns modified (ISO timestamp of the property's last change, for change-detection / cache-busting) and apply_price (the pricing-model flag: nightly / weekly / monthly / fixed). (#1386)
  • property.cancellation-policy:read added to the scope catalogue (admin docs) as a served read scope (low sensitivity) — the per-property analog of bookings.cancellation-policy:read.

Admin API — 2026-06-18​

Pricing/discount WRITES are now reachable with an admin API key, so a Read & write key carrying property.pricing:write (or an admin/owner JWT) can manage discounts and the shared occupancy-discount groups over the API — not just read them. The pricing hard rules (admin docs) (GET-before-write, Idempotency-Key, one property per run, verify) apply, and every endpoint also requires the caller to be an admin or the property's owner.

Added​

  • Occupancy-discount GROUPS (shared preset groups linked to many properties) — GET /occupancy-discounts/{id} (single read, admin-API-key callable; the key response is PII-free, omitting the staff user object), POST /occupancy-discounts, PUT /occupancy-discounts/{id} (replaces all of the group's date-window rows), DELETE /occupancy-discounts/{id}. The LIST — GET /occupancy-discounts — stays JWT-only (it embeds each group's owner name). Ships with bb_app_api #1352.
  • Per-property discount writes — POST/PUT/DELETE /properties/{id}/discounts/{low-occupancy|early-bird|late-availability|short-break-rules} and PATCH /properties/{id}/security-deposit (security/damage deposit only — distinct from the payment-deposit PUT /properties/{id}/deposit). Authorized for the admin API key in bb_app_api #1335.

Changed​

  • property.pricing:write moves from the roadmap to a served write scope in the scope catalogue (admin docs) — it now backs the discount/deposit/occupancy-group writes above (alongside the existing segment-pricing / pricing-model writes).

:::note Propagation Editing a shared occupancy-discount group does not currently bump the linked properties' price-propagation flag, so changes reach the OTA channels at the next daily price push. :::

Admin API — 2026-06-15​

Docs polish (review follow-up). Added required field lists to the bookings and channel-arrival-status 200-response schemas so generated clients and validators treat the always-present fields as guaranteed (nullable values stay nullable). No contract change.

Admin API — 2026-06-09​

Two new admin read endpoints so internal tooling can retire the read-only database tunnel. Both authenticate with an admin API key or an admin/owner JWT, and are scoped per property.

Added​

  • GET /properties/{id}/bookings — recent bookings for a property as a PII-free summary (dates, nights, party size, total price, the two discount amounts, channel and a cancellation flag). Filters: since/until (on the booking creation date, until inclusive), status, includeBlocks, limit, offset. Scope: bookings.recent:read.
  • GET /properties/{id}/channel-arrival-status — whether a property's changeover / arrival-day rule has reached the OTA channel feed (Airbnb / Booking.com via Rentals United): feed freshness, the arrival-open weekdays and the decoded changeover pattern. Scope: property.channel-status:read (new).

Neither endpoint returns guest PII; payment detail stays behind the audited bookings.payments:read scope.

Admin API — 2026-06-09​

Owner pricing-analysis reads are now reachable with an admin API key (scope property.pricing:read), so pricing reviews can run via the API instead of a database tunnel:

  • GET /properties/{id}/comparable-pricing — seasonal weekly-price percentiles across comparable properties
  • GET /properties/{id}/achieved-pricing — own realised weekly rates per season + a leap-year-aware BookingBrain occupancy figure
  • GET /properties/{id}/discounts, GET /properties/{id}/length-stay-discounts — discount levers

These join the existing segment-pricing / short-breaks / nightly-settings reads. The percentile maths was corrected to linear interpolation, and achieved-pricing gained medianWeekly + bbOccupancy. See Admin Data API → Pricing configuration (admin docs).

v2.0.0 — 2026-03-19​

:::caution Historical entry — contains errors This launch entry is preserved as originally published, but parts of it were never true: the API has always been served under /api/v1 (the "v2.0.0" label referred to the docs release, not the URL), and the sandbox key listed under Features was never provisioned — see the 2026-08-07 corrections above. :::

Initial public release of the Booking Brain Developer API.

Endpoints (22)​

  • Property Search — GET /search, GET /specialoffers
  • Property Details — GET /properties/{id}, GET /properties/slug/{slug}, GET /properties/{id}/extras, GET /properties/{id}/bedrooms, GET /properties/{id}/owner-contact, GET /properties/{id}/images, GET /properties/{id}/reviews, GET /properties/{id}/specialoffers
  • Availability & Pricing — GET /properties/{id}/unavailableDates, GET /properties/{id}/startDays, GET /properties/{id}/shortBreaks, GET /properties/{id}/start-dates, POST /properties/{id}/get-price, GET /properties/{id}/available-nights
  • Booking — POST /bookings/save, POST /bookings/validate-voucher
  • Payment — POST /bookings/processPayment
  • Places — GET /places, GET /places/{slug}
  • Usage — GET /usage/stats, GET /usage/logs

Features​

  • API key authentication via X-API-Key header
  • Sandbox key for development (bb_sandbox_test_key_do_not_use_in_production)
  • Per-minute rate limiting with X-RateLimit-* headers
  • IP whitelisting and origin restrictions for production keys
  • Full OpenAPI 3.0 specification at /openapi.yaml
  • Machine-readable documentation at /llms.txt
  • Postman collection at /bookingbrain-api.postman_collection.json

Documentation​

  • Developer portal launched at docs.bookingbrain.com
  • Quick start guide, authentication guide, error handling reference, booking flow walkthrough
  • AI integration guide with function calling examples
  • Interactive API reference with code samples in 6 languages