Create a booking
POST /v1/bookings
With hold_id it converts the hold instead of taking new capacity. payment.mode of deposit or full creates a Stripe PaymentIntent on the connected account and answers with payment_intent, whose client_secret is returned once and is never stored: an idempotent replay answers with the same booking and client_secret: null. payment.mode: "entitlement", and any recurrence, answer 400 not_yet_supported. In the live environment of an account on the free plan, a booking past the confirmed live bookings the plan includes this month, or a payment that would take the month past the included paid volume (param: "payment.mode"), answers 402 plan_limit_reached and takes nothing; the test environment is never counted.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters ”The dated API version to speak. Defaults to 2026-09-01; an unsupported value is a 400.
Example
2026-09-01Which Bookrail tool the caller is, recorded as actor.via on every event the request writes. A closed list: an unknown value is a 400. Absent means the request declared no tool.
Retry-safety key, 1 to 255 characters. The same key within 24 hours replays the first response, errors included, and never produces a second effect.
Request Body required
Section titled “Request Body required ”object
Identifier of a service, prefixed with svc_.
Example
svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cISO 8601 instant with an explicit offset. Any offset is accepted on input; every instant is returned in UTC.
Example
2026-09-08T07:00:00ZIdentifier of a customer, prefixed with cus_.
Example
cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cobject
IANA time zone name.
Example
Europe/RomeFree-form key/value pairs stored with the object and returned untouched.
object
Free-form key/value pairs stored with the object and returned untouched.
object
Identifier of a hold, prefixed with hold_.
Example
hold_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cobject
Responses
Section titled “ Responses ”Created.
object
Identifier of a booking, prefixed with bk_.
Example
bk_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cIdentifier of a service, prefixed with svc_.
Example
svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cIdentifier of a customer, prefixed with cus_.
Example
cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cIdentifier of a hold, prefixed with hold_.
Example
hold_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZAmount in the minor unit of the currency (cents for EUR).
object
Which service.pricing_rules entry priced this booking, frozen at creation. null when the flat service price applied.
object
Position in service.pricing_rules.
The rule label, when it has one.
The policy frozen at creation, as stored. null when the service had none.
Identifier of a booking, prefixed with bk_.
Example
bk_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cIdentifier of a booking, prefixed with bk_.
Example
bk_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZWhen a booking waiting for its payment is cancelled and its slot released. null on every booking that is not waiting for money.
Example
2026-09-08T07:00:00Zobject
Identifier of a resource, prefixed with res_.
Example
res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cPresent on a booking allocation, absent on the allocations of a hold.
Example
ball_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cobject
Identifier of a resource, prefixed with res_.
Example
res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cIdentifier of a location, prefixed with loc_.
Example
loc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cIdentifier of a schedule, prefixed with sch_.
Example
sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cobject
Optional tenant this object belongs to, for multi-tenant customers.
Free-form key/value pairs stored with the object and returned untouched.
object
The environment of the API key that created the object.
ISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZPresent only with expand[]=schedule. null when the resource has none.
object
Identifier of a schedule, prefixed with sch_.
Example
sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cobject
Identifier of a schedule_rule, prefixed with shr_.
Example
shr_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cIdentifier of a schedule, prefixed with sch_.
Example
sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cobject
Identifier of a schedule_exception, prefixed with she_.
Example
she_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cIdentifier of a schedule, prefixed with sch_.
Example
sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cFree-form key/value pairs stored with the object and returned untouched.
object
The environment of the API key that created the object.
ISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZOptional tenant this object belongs to, for multi-tenant customers.
Free-form key/value pairs stored with the object and returned untouched.
object
The environment of the API key that created the object.
ISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZISO 8601 instant in UTC.
Example
2026-09-08T07:00:00Zobject
Identifier of a customer, prefixed with cus_.
Example
cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cOptional tenant this object belongs to, for multi-tenant customers.
Free-form key/value pairs stored with the object and returned untouched.
object
The environment of the API key that created the object.
ISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZPresent only with expand[]=payments: every payment and refund of this booking, oldest first. Never carries a client_secret: an expansion makes no call to Stripe.
object
Identifier of a payment, prefixed with pay_.
Example
pay_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cIdentifier of a booking, prefixed with bk_.
Example
bk_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cpending covers every Stripe state that is not final: requires_payment_method, requires_action, processing. Read provider_status for the detail.
How much of this payment has come back, cumulative.
pi_... for a payment, re_... for a refund. null until Stripe answered.
Example
acct_1234567890For a refund: the payment it gives back.
Example
pay_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cRead from Stripe, only for a pending payment. null on a list, on a refund, and when Stripe did not answer.
Stripe’s own status for the intent, read at request time. null as above.
Free-form key/value pairs stored with the object and returned untouched.
object
The environment of the API key that created the object.
ISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZISO 8601 instant in UTC.
Example
2026-09-08T07:00:00ZPresent and null when the booking takes no payment.
object
The Stripe PaymentIntent.
Example
pi_3AbcPass it to Stripe.js. Returned once, here; null on an idempotent replay, because it is never stored.
ISO 4217, upper case, as the booking froze it.
Stripe’s own status for the intent.
The connected account the intent lives on. Pass it as stripeAccount.
Example
acct_1234567890The platform’s publishable key. Initialise Stripe.js with it.
Example
pk_test_1234567890The Bookrail payment this intent belongs to.
Example
pay_0198f0c2a1b47e2e9a1c0f4d5e6a7b8cHeaders
Section titled “Headers ”Identifier of this request. Quote it to support.
The API version this response was produced with.
true when the body is the stored answer of an earlier request with the same Idempotency-Key.
Requests this key may have in flight at one instant: the burst of its policy.
Requests this key may still make right now, as a whole number.
Whole seconds until RateLimit-Remaining is back at RateLimit-Limit.
unavailable when no limit could be applied to this request, because the store that holds the counters did not answer. The three counters are then absent and the request was served.
<confirmed>/<included>: the confirmed live bookings of the account this month, over the ones its plan includes, as they stood when this request started. On responses to live keys only, and absent for a plan whose included bookings are negotiated and for a key scoped to a tenant.
Error codes: deposit_not_configured, duration_not_offered, hold_mismatch, idempotency_key_reused, invalid_body, not_yet_supported, parameter_invalid, parameter_missing, payment_amount_invalid, price_missing, resource_not_eligible, service_without_duration, unsupported_api_version.
object
object
Machine readable code. The set is per operation; each response below lists the ones it can produce.
The field or header the error is about, when there is one.
What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.
Headers
Section titled “Headers ”Identifier of this request. Quote it to support.
The API version this response was produced with.
Requests this key may have in flight at one instant: the burst of its policy.
Requests this key may still make right now, as a whole number.
Whole seconds until RateLimit-Remaining is back at RateLimit-Limit.
unavailable when no limit could be applied to this request, because the store that holds the counters did not answer. The three counters are then absent and the request was served.
<confirmed>/<included>: the confirmed live bookings of the account this month, over the ones its plan includes, as they stood when this request started. On responses to live keys only, and absent for a plan whose included bookings are negotiated and for a key scoped to a tenant.
Error codes: invalid_api_key, invalid_authorization_header, missing_api_key, revoked_api_key.
object
object
Machine readable code. The set is per operation; each response below lists the ones it can produce.
The field or header the error is about, when there is one.
What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.
Headers
Section titled “Headers ”Identifier of this request. Quote it to support.
The API version this response was produced with.
Requests this key may have in flight at one instant: the burst of its policy.
Requests this key may still make right now, as a whole number.
Whole seconds until RateLimit-Remaining is back at RateLimit-Limit.
unavailable when no limit could be applied to this request, because the store that holds the counters did not answer. The three counters are then absent and the request was served.
<confirmed>/<included>: the confirmed live bookings of the account this month, over the ones its plan includes, as they stood when this request started. On responses to live keys only, and absent for a plan whose included bookings are negotiated and for a key scoped to a tenant.
Error codes: plan_limit_reached.
object
object
Machine readable code. The set is per operation; each response below lists the ones it can produce.
The field or header the error is about, when there is one.
What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.
Headers
Section titled “Headers ”Identifier of this request. Quote it to support.
The API version this response was produced with.
Requests this key may have in flight at one instant: the burst of its policy.
Requests this key may still make right now, as a whole number.
Whole seconds until RateLimit-Remaining is back at RateLimit-Limit.
unavailable when no limit could be applied to this request, because the store that holds the counters did not answer. The three counters are then absent and the request was served.
<confirmed>/<included>: the confirmed live bookings of the account this month, over the ones its plan includes, as they stood when this request started. On responses to live keys only, and absent for a plan whose included bookings are negotiated and for a key scoped to a tenant.
Error codes: resource_missing.
object
object
Machine readable code. The set is per operation; each response below lists the ones it can produce.
The field or header the error is about, when there is one.
What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.
Headers
Section titled “Headers ”Identifier of this request. Quote it to support.
The API version this response was produced with.
Requests this key may have in flight at one instant: the burst of its policy.
Requests this key may still make right now, as a whole number.
Whole seconds until RateLimit-Remaining is back at RateLimit-Limit.
unavailable when no limit could be applied to this request, because the store that holds the counters did not answer. The three counters are then absent and the request was served.
<confirmed>/<included>: the confirmed live bookings of the account this month, over the ones its plan includes, as they stood when this request started. On responses to live keys only, and absent for a plan whose included bookings are negotiated and for a key scoped to a tenant.
Error codes: hold_expired, hold_not_active, idempotency_key_in_progress, serialization_failure, slot_unavailable, stripe_not_connected.
object
object
Machine readable code. The set is per operation; each response below lists the ones it can produce.
The field or header the error is about, when there is one.
What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.
Headers
Section titled “Headers ”Identifier of this request. Quote it to support.
The API version this response was produced with.
Requests this key may have in flight at one instant: the burst of its policy.
Requests this key may still make right now, as a whole number.
Whole seconds until RateLimit-Remaining is back at RateLimit-Limit.
unavailable when no limit could be applied to this request, because the store that holds the counters did not answer. The three counters are then absent and the request was served.
<confirmed>/<included>: the confirmed live bookings of the account this month, over the ones its plan includes, as they stood when this request started. On responses to live keys only, and absent for a plan whose included bookings are negotiated and for a key scoped to a tenant.
Error codes: customer_limit_reached, min_notice_violated, outside_booking_window, start_not_on_grid.
object
object
Machine readable code. The set is per operation; each response below lists the ones it can produce.
The field or header the error is about, when there is one.
What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.
Headers
Section titled “Headers ”Identifier of this request. Quote it to support.
The API version this response was produced with.
Requests this key may have in flight at one instant: the burst of its policy.
Requests this key may still make right now, as a whole number.
Whole seconds until RateLimit-Remaining is back at RateLimit-Limit.
unavailable when no limit could be applied to this request, because the store that holds the counters did not answer. The three counters are then absent and the request was served.
<confirmed>/<included>: the confirmed live bookings of the account this month, over the ones its plan includes, as they stood when this request started. On responses to live keys only, and absent for a plan whose included bookings are negotiated and for a key scoped to a tenant.
Error codes: rate_limited.
object
object
Machine readable code. The set is per operation; each response below lists the ones it can produce.
The field or header the error is about, when there is one.
What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.
Headers
Section titled “Headers ”Identifier of this request. Quote it to support.
The API version this response was produced with.
Requests this key may have in flight at one instant: the burst of its policy.
Requests this key may still make right now, as a whole number.
Whole seconds until RateLimit-Remaining is back at RateLimit-Limit.
unavailable when no limit could be applied to this request, because the store that holds the counters did not answer. The three counters are then absent and the request was served.
<confirmed>/<included>: the confirmed live bookings of the account this month, over the ones its plan includes, as they stood when this request started. On responses to live keys only, and absent for a plan whose included bookings are negotiated and for a key scoped to a tenant.
Whole seconds to wait before sending this request again. At least 1.
Error codes: internal_error.
object
object
Machine readable code. The set is per operation; each response below lists the ones it can produce.
The field or header the error is about, when there is one.
What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.
Headers
Section titled “Headers ”Identifier of this request. Quote it to support.
The API version this response was produced with.
Requests this key may have in flight at one instant: the burst of its policy.
Requests this key may still make right now, as a whole number.
Whole seconds until RateLimit-Remaining is back at RateLimit-Limit.
unavailable when no limit could be applied to this request, because the store that holds the counters did not answer. The three counters are then absent and the request was served.
<confirmed>/<included>: the confirmed live bookings of the account this month, over the ones its plan includes, as they stood when this request started. On responses to live keys only, and absent for a plan whose included bookings are negotiated and for a key scoped to a tenant.
Error codes: stripe_provider_error, stripe_unreachable.
object
object
Machine readable code. The set is per operation; each response below lists the ones it can produce.
The field or header the error is about, when there is one.
What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.
Headers
Section titled “Headers ”Identifier of this request. Quote it to support.
The API version this response was produced with.
Requests this key may have in flight at one instant: the burst of its policy.
Requests this key may still make right now, as a whole number.
Whole seconds until RateLimit-Remaining is back at RateLimit-Limit.
unavailable when no limit could be applied to this request, because the store that holds the counters did not answer. The three counters are then absent and the request was served.
<confirmed>/<included>: the confirmed live bookings of the account this month, over the ones its plan includes, as they stood when this request started. On responses to live keys only, and absent for a plan whose included bookings are negotiated and for a key scoped to a tenant.
Error codes: stripe_not_configured.
object
object
Machine readable code. The set is per operation; each response below lists the ones it can produce.
The field or header the error is about, when there is one.
What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.
Headers
Section titled “Headers ”Identifier of this request. Quote it to support.
The API version this response was produced with.
Requests this key may have in flight at one instant: the burst of its policy.
Requests this key may still make right now, as a whole number.
Whole seconds until RateLimit-Remaining is back at RateLimit-Limit.
unavailable when no limit could be applied to this request, because the store that holds the counters did not answer. The three counters are then absent and the request was served.
<confirmed>/<included>: the confirmed live bookings of the account this month, over the ones its plan includes, as they stood when this request started. On responses to live keys only, and absent for a plan whose included bookings are negotiated and for a key scoped to a tenant.