Cancel the whole booking as its buyer, at the refund the guest was shown

POST

/account/bookings/{booking_id}/cancellation

curl --request POST \
  --url https://quikstik-core.fly.dev/account/bookings/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/cancellation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "acknowledged_refund_minor": 1 }'

• Production

Issues the operator CancelBookingCommand { reason: customer_initiated, units: null } with the guest as actor, through the same cancel sink as POST /cancellations; the refund fraction is the tenant schedule’s tier at the moment of the call. The body carries only the figure the guest was shown: the server recomputes it, and a different current figure is 409 quote_changed with the current quote (never a cancellation on a stale number). Idempotency-Key is required (the ledger’s own key is derived per booking, so a reused client key can never swallow another booking’s refund). Whole booking only — rider removal is the amendment lane. The weather waiver is an operator action and is not promised here.

Authorizations

• bearerAuth

Parameters

Path Parameters

booking_id

required

string format: uuid

Header Parameters

Idempotency-Key

required

string

>= 1 characters

Idempotency key for the command envelope. A retry with the same key is a no-op.

Request Body^required

Media typeapplication/json

object

acknowledged_refund_minor

required

The refund the guest was shown. Never posted — only compared to the server’s figure.

integer format: int64

Example ^generated

{
  "acknowledged_refund_minor": 1
}

Responses

202

Cancelled; the ledger will post exactly refund_minor when it drains the event

Media typeapplication/json

object

booking_id

required

string format: uuid

status

required

string

Allowed values: cancelled

refund_minor

required

integer format: int64

refund_bps

required

integer

currency

required

string

Example

{
  "status": "cancelled"
}

400

Malformed body

Media typeapplication/json

object

reason

required

string

Example ^generated

{
  "reason": "example"
}

401

Missing or invalid session bearer token

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}

403

The session’s effect authority does not cover this operation

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}

404

Expired, consumed, unknown, or unresolvable — indistinguishable by design

Media typeapplication/json

object

reason

required

string

Example ^generated

{
  "reason": "example"
}

409

quote_changed (body carries current) or not_cancellable (detail: already_cancelled | ota_booking | departed | needs_staff)

Media typeapplication/json

object

reason

required

Stable machine reason

string

detail

Finer machine code under reason

string

current

object

booking_id

required

string format: uuid

refund_minor

required

Minor units the card gets back

integer format: int64

refund_bps

required

integer

<= 10000

tier_hours

Hours-before-departure the applying tier requires; absent when no tier applies

integer

deadline_at

Last instant this refund still applies; absent when no tier applies

string format: date-time

currency

required

string

Example ^generated

{
  "reason": "example",
  "detail": "example",
  "current": {
    "booking_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "refund_minor": 1,
    "refund_bps": 1,
    "tier_hours": 1,
    "deadline_at": "2026-04-15T12:00:00Z",
    "currency": "example"
  }
}

503

No durable backend is wired for this operation (fail-closed)

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}