Skip to content
Quikstik Developers

Cancel a whole departure and fully refund every active booking on it

POST
/departure-cancellations
curl --request POST \
  --url https://quikstik-core.fly.dev/departure-cancellations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-tenant-id: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --data '{ "departure_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "effective_date": { "year": 1, "month": 1, "day": 1 } }'

Operator cancellation of a departure (weather, mechanical, too few guests). Runs the trip-cancel cascade as one resumable unit: enumerate every active booking on the departure, mark each cancelled and enqueue a full refund (cancellation.requested, the trip never happened — the time-to-departure schedule is not consulted), then mark the departure cancelled. The ledger settles the refunds asynchronously. The cascade is idempotent and resumable — each refund carries a stable key derived from its booking id and only active bookings are enumerated, so a re-run after a partial failure completes the rest and double-refunds nothing; no Idempotency-Key is required. Fail-closed: 503 when no backend is wired. The response reports how many bookings were cancelled.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
x-tenant-id
required
string format: uuid

Tenant identifier (UUID).

Authn/authz semantics are intentionally TBD for this contract slice; this header exists to keep the contract explicitly multi-tenant from day 0.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
departure_id
required

The departure being cancelled (every active booking on it is refunded).

string format: uuid
effective_date
required

Business/effective date of the cancellation, for period close.

object
year
required
integer format: int32
month
required
integer
>= 1 <= 12
day
required
integer
>= 1 <= 31

Example generated

{
  "departure_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "effective_date": {
    "year": 1,
    "month": 1,
    "day": 1
  }
}

Responses

Section titled “Responses”

202

Section titled “202”

Departure cancellation accepted; active bookings cancelled and refunds enqueued

Media typeapplication/json
object
departure_id
required
string format: uuid
status
required
string
Allowed values: cancelled
cancelled_count
required

How many active bookings the cascade cancelled and refund-requested.

integer format: int32

Example 

{
  "status": "cancelled"
}

401

Section titled “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

Section titled “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"
}

503

Section titled “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"
}