Create a booking

POST /api/v1/bookings

The heart of the product. No business rule is rewritten here: availability, buffer, opening hours, the rate grid, the currency, the timezone and the plan ceiling are all enforced by the same service the app calls.

The date and the start time are local to the organization, not instants: send date: "2026-09-12" and startMinute: 540 for 09:00 local. Read settings.timezone from /api/v1/me if you need to know which local that is.

Authorization

The product gives members the right to create bookings — they are often the ones with the customer on the phone. Refusing them here would make the API stricter than the screen.

Request body

Example

curl -X POST -H "x-api-key: $VILLASLOT_API_KEY" -H "content-type: application/json" \
  -d '{"propertyId":"1f0a…","customerId":"8d3e…","date":"2026-09-12","startMinute":540,"durationMinutes":120,"status":"HOLD"}' \
  "https://villaslot.app/api/v1/bookings"

Response

• 201 Created — the booking. A HOLD carries holdExpiresAt; a CONFIRMED does not.

What it refuses

• 409 Conflict — the booking was not created, and detail.reason says why:

  reason	Meaning
  OVERLAP	The slot, or its buffer, is taken
  CLOSED	The villa is closed that day
  OUTSIDE_OPENING_HOURS	The slot falls outside the opening range
  INVALID_INTERVAL	End before start
  DURATION_NOT_PRICED	That duration has no rate for this villa
  CURRENCY_NOT_CONFIGURED	The organization has not chosen a currency
  PROPERTY_NOT_BOOKABLE	Unknown, archived, or another organization's villa
  CUSTOMER_NOT_FOUND	Unknown, or another organization's customer

• 409 Conflict — the plan limit for bookings is reached.

• 422 Unprocessable Entity — a malformed field; details lists them.

• 401 Unauthorized — missing or invalid key, or a key whose bearer left the organization.

• 404 Not Found — unknown id, or an id belonging to another organization. The two are deliberately indistinguishable.

• 429 Too Many Requests — over 120 requests in a minute for this key.

Agent recipe

Ask availability first, then create — a refused POST costs a round trip and tells you no more than the free slots already did:

const {data} = await get(
  `/api/v1/properties/${propertyId}/availability?date=2026-09-12&durationMinutes=120`
)
if (data.slots.length === 0) return 'no slot that day'

await post('/api/v1/bookings', {
  propertyId, customerId, date: '2026-09-12', startMinute: 540,
  durationMinutes: 120, status: 'HOLD',
})

Notes

• Overriding a conflict is not available over the API. Forcing a booking onto a taken slot is a deliberate human decision, made on screen after seeing what it collides with.
• Overnight stays are not covered by this endpoint yet.