Skip to content
Bookrail

Search is only available in production builds. Try building and previewing the site to test it out locally.

Cancel a booking

POST
/v1/bookings/{id}/cancel

by defaults to customer. override_refund_percent beats every tier, for any by. No money moves: the amounts written are expectations.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required

Identifier of the booking.

string

Header Parameters

Section titled “Header Parameters ”
Bookrail-Version

The dated API version to speak. Defaults to 2026-09-01; an unsupported value is a 400.

string
Example
2026-09-01
Bookrail-Actor

Which 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.

string
Allowed values: mcp cli sdk dashboard
Idempotency-Key

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.

string
>= 1 characters <= 255 characters

Request Body required

Section titled “Request Body required ”
object
reason
string | null
<= 1000 characters
by
string
Allowed values: customer provider system
override_refund_percent
number | null
<= 100

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Success.

object
id
required

Identifier of a booking, prefixed with bk_.

string
/^bk_[0-9a-f]{32}$/
Example
bk_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: booking
status
required
string
Allowed values: held pending confirmed in_progress completed cancelled no_show rescheduled
service_id
required

Identifier of a service, prefixed with svc_.

string
/^svc_[0-9a-f]{32}$/
Example
svc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
customer_id
required

Identifier of a customer, prefixed with cus_.

string | null
/^cus_[0-9a-f]{32}$/
Example
cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
hold_id
required

Identifier of a hold, prefixed with hold_.

string | null
/^hold_[0-9a-f]{32}$/
Example
hold_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
start
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
end
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
duration_minutes
required
integer
timezone
required
string
quantity
required
integer
price
required

Amount in the minor unit of the currency (cents for EUR).

object
amount
required
integer
currency
required
string
price_rule
required

Which service.pricing_rules entry priced this booking, frozen at creation. null when the flat service price applied.

object
index
required

Position in service.pricing_rules.

integer
label
required

The rule label, when it has one.

string | null
amount_paid
required
integer
amount_due
required
integer
amount_refunded
required
integer
policy_snapshot
required

The policy frozen at creation, as stored. null when the service had none.

object | null
source
required
string
Allowed values: api widget portal import
notes
required
string | null
cancelled_by
required
string | null
Allowed values: customer provider system
cancellation_reason
required
string | null
refund_percent
required
number | null
refund_amount_expected
required
integer | null
no_show_charge_expected
required
integer | null
reschedule_fee_expected
required
integer | null
reschedule_count
required
integer
rescheduled_from_booking_id
required

Identifier of a booking, prefixed with bk_.

string | null
/^bk_[0-9a-f]{32}$/
Example
bk_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
rescheduled_to_booking_id
required

Identifier of a booking, prefixed with bk_.

string | null
/^bk_[0-9a-f]{32}$/
Example
bk_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
confirmed_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
checked_in_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
cancelled_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
completed_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
no_show_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
rescheduled_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
next_transition
required
string | null
Allowed values: start complete no_show
next_transition_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
allocations
required
Array<object>
object
object
required
string
Allowed values: booking_allocation
resource_id
required

Identifier of a resource, prefixed with res_.

string
/^res_[0-9a-f]{32}$/
Example
res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
role
required
string | null
capacity_used
required
integer
id

Present on a booking allocation, absent on the allocations of a hold.

string
/^ball_[0-9a-f]{32}$/
Example
ball_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
resource
object
id
required

Identifier of a resource, prefixed with res_.

string
/^res_[0-9a-f]{32}$/
Example
res_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: resource
name
required
string
type
required
string
location_id
required

Identifier of a location, prefixed with loc_.

string | null
/^loc_[0-9a-f]{32}$/
Example
loc_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
schedule_id
required

Identifier of a schedule, prefixed with sch_.

string | null
/^sch_[0-9a-f]{32}$/
Example
sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
capacity
required
integer
attributes
required
object
key
additional properties
status
required
string
Allowed values: active inactive
tenant_id
required

Optional tenant this object belongs to, for multi-tenant customers.

string | null
metadata
required

Free-form key/value pairs stored with the object and returned untouched.

object
key
additional properties
environment
required

The environment of the API key that created the object.

string
Allowed values: test live
created_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
updated_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
schedule

Present only with expand[]=schedule. null when the resource has none.

object
id
required

Identifier of a schedule, prefixed with sch_.

string
/^sch_[0-9a-f]{32}$/
Example
sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: schedule
name
required
string
timezone
required
string | null
rules
required
Array<object>
object
id
required

Identifier of a schedule_rule, prefixed with shr_.

string
/^shr_[0-9a-f]{32}$/
Example
shr_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: schedule_rule
schedule_id
required

Identifier of a schedule, prefixed with sch_.

string
/^sch_[0-9a-f]{32}$/
Example
sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
days_of_week
required
Array<integer>
start_time
required
string | null
end_time
required
string | null
valid_from
required
string | null
valid_until
required
string | null
exceptions
required
Array<object>
object
id
required

Identifier of a schedule_exception, prefixed with she_.

string
/^she_[0-9a-f]{32}$/
Example
she_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: schedule_exception
schedule_id
required

Identifier of a schedule, prefixed with sch_.

string
/^sch_[0-9a-f]{32}$/
Example
sch_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
date
required
string
type
required
string
Allowed values: closed open
start_time
required
string | null
end_time
required
string | null
reason
required
string | null
metadata
required

Free-form key/value pairs stored with the object and returned untouched.

object
key
additional properties
environment
required

The environment of the API key that created the object.

string
Allowed values: test live
created_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
updated_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
tenant_id
required

Optional tenant this object belongs to, for multi-tenant customers.

string | null
metadata
required

Free-form key/value pairs stored with the object and returned untouched.

object
key
additional properties
environment
required

The environment of the API key that created the object.

string
Allowed values: test live
created_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
updated_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
customer
object
id
required

Identifier of a customer, prefixed with cus_.

string
/^cus_[0-9a-f]{32}$/
Example
cus_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: customer
external_id
required
string | null
email
required
string | null
phone
required
string | null
name
required
string | null
timezone
required
string | null
locale
required
string | null
tenant_id
required

Optional tenant this object belongs to, for multi-tenant customers.

string | null
metadata
required

Free-form key/value pairs stored with the object and returned untouched.

object
key
additional properties
environment
required

The environment of the API key that created the object.

string
Allowed values: test live
created_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z
updated_at
required

ISO 8601 instant in UTC.

string | null format: date-time
Example
2026-09-08T07:00:00Z

Headers

Section titled “Headers ”
Bookrail-Request-Id
required

Identifier of this request. Quote it to support.

string
Bookrail-Version
required

The API version this response was produced with.

string
Idempotent-Replayed

true when the body is the stored answer of an earlier request with the same Idempotency-Key.

string

400

Section titled “400 ”

Error codes: idempotency_key_reused, invalid_body, parameter_invalid, parameter_missing, unsupported_api_version.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required

Identifier of this request. Quote it to support.

string
Bookrail-Version
required

The API version this response was produced with.

string

401

Section titled “401 ”

Error codes: invalid_api_key, invalid_authorization_header, missing_api_key, revoked_api_key.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required

Identifier of this request. Quote it to support.

string
Bookrail-Version
required

The API version this response was produced with.

string

404

Section titled “404 ”

Error codes: resource_missing.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required

Identifier of this request. Quote it to support.

string
Bookrail-Version
required

The API version this response was produced with.

string

409

Section titled “409 ”

Error codes: idempotency_key_in_progress, invalid_transition, serialization_failure.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required

Identifier of this request. Quote it to support.

string
Bookrail-Version
required

The API version this response was produced with.

string

422

Section titled “422 ”

Error codes: complete_too_early, no_show_too_early.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required

Identifier of this request. Quote it to support.

string
Bookrail-Version
required

The API version this response was produced with.

string

500

Section titled “500 ”

Error codes: internal_error.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required

Identifier of this request. Quote it to support.

string
Bookrail-Version
required

The API version this response was produced with.

string