Confirm a booking
POST /v1/bookings/{id}/confirm
A booking whose payment is still in flight answers 409 payment_pending: confirming it would tell the customer the slot is theirs while the card may still be refused. Wait for the payment, or cancel the booking.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Identifier of the booking.
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
Responses
Section titled “ Responses ”Success.
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:00ZHeaders
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: idempotency_key_reused, invalid_body, parameter_invalid, parameter_missing, 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: 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: idempotency_key_in_progress, invalid_transition, payment_pending, serialization_failure.
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: complete_too_early, no_show_too_early.
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.