Bookings

Bookings are stays: an accommodation (pitch type), a date range, a party of guests, and a server-computed price. A booking holds inventory for its nights — creating one decrements each night's allocation vacancy, cancelling one restores it, all transactionally.

The booking object

{
  "id": "xK9dP2qA",
  "object": "booking",
  "site": "8Mj2CovDxz",
  "status": "confirmed",
  "accommodation": "0F7p9sGHx",
  "customer": null,
  "guest": {
    "first_name": "Alex",
    "last_name": "Rider",
    "email": "alex@example.com",
    "phone": "+441234567890"
  },
  "party": { "adults": 2, "children": 1, "infants": 0, "pets": 1 },
  "arrive": 1793107200,
  "depart": 1793280000,
  "nights": 2,
  "currency": "gbp",
  "accommodation_cost": 12345,
  "remainder": 12345,
  "payment_amount": 12345,
  "cost_detail": {
    "accommodation_cost": 10000,
    "adult_cost": 2000,
    "child_cost": 345,
    "infant_cost": 0,
    "pet_cost": 0,
    "total": 12345
  },
  "source": "api",
  "checked_in": false,
  "created": 1793061121,
  "metadata": {}
}

• status — hold (awaiting payment), confirmed, or cancelled.
• accommodation_cost / remainder / payment_amount — minor units. payment_amount is what the guest owes via the portal payment flow.
• source — where the booking came from: website, api, pitchup, ...

Endpoints

Method	Path	Description
GET	/v1/bookings	List (filters + pagination)
POST	/v1/bookings	Create (server-priced, allocation-aware)
GET	/v1/bookings/{id}	Retrieve (expand[]: accommodation, customer)
PATCH	/v1/bookings/{id}	Update guest details, party, metadata
POST	/v1/bookings/{id}/confirm	hold → confirmed
POST	/v1/bookings/{id}/cancel	Cancel + restore inventory

Create a booking

The server is the only pricing authority: accommodation_cost is computed from the rate sheet inside the same transaction that checks inventory, so a created booking is always both available and correctly priced.

Required fields: accommodation (id), arrive, depart, adults. Optional: children, infants, pets, status (hold|confirmed, default confirmed), customer (id), first_name, last_name, email, phone, source, metadata.

curl -s $API/v1/bookings -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: rally-booking-42" -H "Content-Type: application/json" \
  -d '{"accommodation":"0F7p9sGHx","arrive":1793107200,"depart":1793280000,
       "adults":2,"children":1,"pets":1,"status":"confirmed",
       "first_name":"Alex","last_name":"Rider","email":"alex@example.com"}'

Errors you should handle:

code	When
resource_missing	Unknown accommodation id
booking_unavailable	Sold out for a night, rates missing for a night, or stay length violates min/max nights
validation_failed	Malformed body or depart ≤ arrive

Cancel a booking

curl -s -X POST "$API/v1/bookings/xK9dP2qA/cancel?reason=guest+request" \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: cancel-xK9dP2qA"

Each night's allocation vacancy is restored atomically. Cancelling an already-cancelled booking returns booking_already_cancelled. Confirming a booking that is not a hold returns booking_not_confirmable.

Listing and filtering

• Equality filters (cursor-paginated): status, accommodation, customer, email, cancelled.
• Range filters: arrive_from / arrive_to (arrival window) and depart_from / depart_to (departure window), unix seconds or ISO 8601.
• Name search: search prefix-matches the booking's searchName ("first last", lowercased), e.g. search=john finds John Smith and Johnny Doe.
• Range and search filters cannot be combined with the equality filters, or with each other, in v1 — one window or one name fragment per query. Split the query (or fetch the name matches, then window client-side).
• Party changes via PATCH do not re-price; cancel and recreate when the price must change.