Skip to content
Booking Engine API Docs

/v1/bookings (POST)

POST
/v1/bookings
curl --request POST \
  --url http://localhost:8787/v1/bookings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "currency": "example", "from": "2026-04-15T12:00:00Z", "guestEmail": "hello@example.com", "guestName": "example", "guestPhone": "example", "occupancyChildren": 1, "paidOffline": false, "partySize": 1, "quantity": 1, "ratePlanId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "resourceId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "to": "2026-04-15T12:00:00Z" }'

Authorizations

Section titled “Authorizations”

Request Body

Section titled “Request Body”
Media typeapplication/json
object
currency
string
>= 3 characters <= 3 characters
from
required
string format: date-time
guestEmail
required
string format: email
guestName
string
>= 1 characters
guestPhone
string
>= 1 characters
occupancyChildren
integer
paidOffline
boolean
partySize
required
integer
> 0
quantity
integer
> 0
ratePlanId
string format: uuid
resourceId
required
string format: uuid
to
required
string format: date-time

Responses

Section titled “Responses”

200

Section titled “200”

The SAME booking a prior request with this Idempotency-Key already created.

Media typeapplication/json
object
booking
required
object
createdAt
required
string
currency
required
string
>= 3 characters <= 3 characters
endsAt
required
string
guestEmail
required
string | null
holdExpiresAt
required
string | null
id
required
string format: uuid
occupancyAdults
required
integer | null
occupancyChildren
required
integer
quantity
required
integer
ratePlanId
required
string | null format: uuid
resourceId
required
string format: uuid
roomTypeId
required
string | null format: uuid
source
required
string
startsAt
required
string
state
required
string
Allowed values: pending held confirmed cancelled checked_in checked_out no_show expired
totalMinorUnits
required
string
/^\d+$/
updatedAt
required
string
payment
required
object
amountMinorUnits
required
string
/^\d+$/
clientSecret
required
string
currency
required
string
>= 3 characters <= 3 characters
reservationId
required
string format: uuid
state
required
string
Allowed values: requires_payment requires_action processing succeeded failed refunded
stripePaymentIntentId
required
string
Example
{
  "booking": {
    "state": "pending"
  },
  "payment": {
    "state": "requires_payment"
  }
}

201

Section titled “201”

paidOffline: true -> the booking, already confirmed, payment: null. Otherwise -> the booking, still held, with a payable PaymentIntent handle.

Media typeapplication/json
object
booking
required
object
createdAt
required
string
currency
required
string
>= 3 characters <= 3 characters
endsAt
required
string
guestEmail
required
string | null
holdExpiresAt
required
string | null
id
required
string format: uuid
occupancyAdults
required
integer | null
occupancyChildren
required
integer
quantity
required
integer
ratePlanId
required
string | null format: uuid
resourceId
required
string format: uuid
roomTypeId
required
string | null format: uuid
source
required
string
startsAt
required
string
state
required
string
Allowed values: pending held confirmed cancelled checked_in checked_out no_show expired
totalMinorUnits
required
string
/^\d+$/
updatedAt
required
string
payment
required
object
amountMinorUnits
required
string
/^\d+$/
clientSecret
required
string
currency
required
string
>= 3 characters <= 3 characters
reservationId
required
string format: uuid
state
required
string
Allowed values: requires_payment requires_action processing succeeded failed refunded
stripePaymentIntentId
required
string
Example
{
  "booking": {
    "state": "pending"
  },
  "payment": {
    "state": "requires_payment"
  }
}

400

Section titled “400”

Missing Idempotency-Key header, from not strictly before to, or (with a room-type resource) a missing/unresolvable rate plan.

Media typeapplication/problem+json
object
code
required
string
Allowed values: idempotency_key_required invalid_window resource_not_found rate_plan_required rate_plan_not_found unavailable no_pricing_rule fx_rate_unavailable resource_locked booking_conflict idempotency_key_conflict stripe_not_configured payment_setup_failed
detail
required
string
status
required
number
title
required
string
type
required
string
Example
{
  "code": "idempotency_key_required"
}

404

Section titled “404”

No such resource (or rate plan) for this tenant.

Media typeapplication/problem+json
object
code
required
string
Allowed values: idempotency_key_required invalid_window resource_not_found rate_plan_required rate_plan_not_found unavailable no_pricing_rule fx_rate_unavailable resource_locked booking_conflict idempotency_key_conflict stripe_not_configured payment_setup_failed
detail
required
string
status
required
number
title
required
string
type
required
string
Example
{
  "code": "idempotency_key_required"
}

409

Section titled “409”

The stay fails availability/restrictions, the resource is locked by a concurrent attempt, it’s already held/booked (the EXCLUDE constraint), this Idempotency-Key is already in use by a different (non-manual) reservation, or (payment-link mode) the tenant has no usable Stripe Connect account.

Media typeapplication/problem+json
Any of:
object
code
required
string
Allowed values: unavailable
detail
required
string
reasons
required
Array<string>
Allowed values: occupancy_exceeded reserved external_block min_stay max_stay closed_to_arrival closed_to_departure stop_sell
status
required
number
title
required
string
type
required
string
Example
{
  "code": "unavailable",
  "reasons": [
    "occupancy_exceeded"
  ]
}

422

Section titled “422”

No applicable pricing rule for one or more nights, or no FX rate available.

Media typeapplication/problem+json
Any of:
object
code
required
string
Allowed values: no_pricing_rule
detail
required
string
missingDates
required
Array<string>
status
required
number
title
required
string
type
required
string
Example
{
  "code": "no_pricing_rule"
}