Skip to content
Quikstik Developers

The booking's policy snapshot and what it allows now

GET
/bookings/{booking_id}/policy
curl --request GET \
  --url https://quikstik-core.fly.dev/bookings/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/policy \
  --header 'Authorization: Bearer <token>' \
  --header 'x-tenant-id: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0'

The one read the portal, the operator app and the agent use to say “you may cancel for $X”. Returns the policy the booking was sold under (its snapshot — later edits to the merchant’s policy never change it) and the resolved verdicts now: whole hours_before departure (rounded toward less notice), the cancel outcome and the reschedule outcome, each with the effective fee, refund_as and who governs (merchant | ota).

source: snapshot is the booking’s own row; source: legacy_schedule is a booking sold before the policy model (not yet backfilled), answered from the merchant’s T-minus schedule exactly as the cancel path does. A cancelled booking still answers (status: cancelled).

Auth: a staff session, an operator key scoped bookings.read, or a customer session that owns the booking (the account reach rule). Any other booking id is 404 booking_not_found for a customer — existence is never confirmed. Cache-Control: private, no-store.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
booking_id
required
string format: uuid

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.

Responses

Section titled “Responses”

200

Section titled “200”

The snapshot and the verdicts now

Media typeapplication/json
object
booking_id
required
string format: uuid
status
required
string
Allowed values: created cancelled
source
required
string
Allowed values: snapshot legacy_schedule
snapshot
required

Null when source is legacy_schedule.

object
seq
required
integer
>= 1
basis
required
string
Allowed values: documents legacy_schedule built_in_default backfill re_resolve
reason
string
nullable
resolved_at_ms
required
integer format: int64
policy_refs
required
Array<object>
object
policy_id
required
string format: uuid
version
required
integer
>= 1
scope_kind
required
string
Allowed values: tenant offering variant channel
scope_ref
required
string
policy
required

The resolved rule set. Every field is present — nothing is left to inherit.

object
cancel
required

Tiers are most-notice-first; the most generous qualifying tier applies, else below.

object
tiers
required
Array<object>
object
min_hours_before
required
integer
refund_bps
required
integer
<= 10000
below
required

One rule’s verdict. For a cancel, refund_all/no_refund/refund are the refund fraction; for a reschedule refund_all means a free change and no_refund means not allowed. ota_governed is produced by resolution for a booking whose channel governs it and is never stored in a document. refund carries bps; fee carries fee.

object
kind
required
string
Allowed values: refund_all no_refund refund fee ota_governed
bps
integer
<= 10000
fee

none as the inner fee of a fee outcome means “use the policy’s own fee”. flat carries minor + currency; percent carries bps; keep_deposit carries nothing.

object
kind
required
string
Allowed values: none flat percent keep_deposit
minor
integer format: int64
currency
string
Allowed values: USD
bps
integer
<= 10000
reschedule
required
object
tiers
required
Array<object>
object
min_hours_before
required
integer
outcome
required

One rule’s verdict. For a cancel, refund_all/no_refund/refund are the refund fraction; for a reschedule refund_all means a free change and no_refund means not allowed. ota_governed is produced by resolution for a booking whose channel governs it and is never stored in a document. refund carries bps; fee carries fee.

object
kind
required
string
Allowed values: refund_all no_refund refund fee ota_governed
bps
integer
<= 10000
fee

none as the inner fee of a fee outcome means “use the policy’s own fee”. flat carries minor + currency; percent carries bps; keep_deposit carries nothing.

object
kind
required
string
Allowed values: none flat percent keep_deposit
minor
integer format: int64
currency
string
Allowed values: USD
bps
integer
<= 10000
below
required

One rule’s verdict. For a cancel, refund_all/no_refund/refund are the refund fraction; for a reschedule refund_all means a free change and no_refund means not allowed. ota_governed is produced by resolution for a booking whose channel governs it and is never stored in a document. refund carries bps; fee carries fee.

object
kind
required
string
Allowed values: refund_all no_refund refund fee ota_governed
bps
integer
<= 10000
fee

none as the inner fee of a fee outcome means “use the policy’s own fee”. flat carries minor + currency; percent carries bps; keep_deposit carries nothing.

object
kind
required
string
Allowed values: none flat percent keep_deposit
minor
integer format: int64
currency
string
Allowed values: USD
bps
integer
<= 10000
fee
required

none as the inner fee of a fee outcome means “use the policy’s own fee”. flat carries minor + currency; percent carries bps; keep_deposit carries nothing.

object
kind
required
string
Allowed values: none flat percent keep_deposit
minor
integer format: int64
currency
string
Allowed values: USD
bps
integer
<= 10000
refund_as
required
object
kind
required
string
Allowed values: money credit
expires_days
integer
weather
required
object
kind
required
string
Allowed values: none clause
decision_hour_local
integer
<= 23
forecast_source
string
rain_chance_bps
integer
<= 10000
fraction_of_ride_bps
integer
<= 10000
outcome
string
Allowed values: full_refund_or_rebook
no_show
required

One rule’s verdict. For a cancel, refund_all/no_refund/refund are the refund fraction; for a reschedule refund_all means a free change and no_refund means not allowed. ota_governed is produced by resolution for a booking whose channel governs it and is never stored in a document. refund carries bps; fee carries fee.

object
kind
required
string
Allowed values: refund_all no_refund refund fee ota_governed
bps
integer
<= 10000
fee

none as the inner fee of a fee outcome means “use the policy’s own fee”. flat carries minor + currency; percent carries bps; keep_deposit carries nothing.

object
kind
required
string
Allowed values: none flat percent keep_deposit
minor
integer format: int64
currency
string
Allowed values: USD
bps
integer
<= 10000
operator_cancel
required
string
Allowed values: refund_all
overrides
required
object
waiver_reasons
required
Array<string>
Allowed values: hardship rain_rule goodwill flight_disruption
text
required

Rendering hints only; the full page renders from the rules.

object
summary_short
required
string
summary_multi_day
string
governs
required

True when the booking’s channel governs (verdicts are ota_governed).

boolean
now
required
object
at_ms
required
integer format: int64
departure_start
required

RFC3339 UTC - the booking’s agreed start (the agreement chain’s; an amendment may have moved it from the departure’s). Notice is measured from it, as the cancel path does.

string
hours_before
required

Whole hours, rounded toward less notice.

integer format: int64
cancel
required
object
outcome
required

One rule’s verdict. For a cancel, refund_all/no_refund/refund are the refund fraction; for a reschedule refund_all means a free change and no_refund means not allowed. ota_governed is produced by resolution for a booking whose channel governs it and is never stored in a document. refund carries bps; fee carries fee.

object
kind
required
string
Allowed values: refund_all no_refund refund fee ota_governed
bps
integer
<= 10000
fee

none as the inner fee of a fee outcome means “use the policy’s own fee”. flat carries minor + currency; percent carries bps; keep_deposit carries nothing.

object
kind
required
string
Allowed values: none flat percent keep_deposit
minor
integer format: int64
currency
string
Allowed values: USD
bps
integer
<= 10000
fee

none as the inner fee of a fee outcome means “use the policy’s own fee”. flat carries minor + currency; percent carries bps; keep_deposit carries nothing.

object
kind
required
string
Allowed values: none flat percent keep_deposit
minor
integer format: int64
currency
string
Allowed values: USD
bps
integer
<= 10000
refund_as
required
object
kind
required
string
Allowed values: money credit
expires_days
integer
governed_by
required
string
Allowed values: merchant ota
reschedule
required
object
outcome
required

One rule’s verdict. For a cancel, refund_all/no_refund/refund are the refund fraction; for a reschedule refund_all means a free change and no_refund means not allowed. ota_governed is produced by resolution for a booking whose channel governs it and is never stored in a document. refund carries bps; fee carries fee.

object
kind
required
string
Allowed values: refund_all no_refund refund fee ota_governed
bps
integer
<= 10000
fee

none as the inner fee of a fee outcome means “use the policy’s own fee”. flat carries minor + currency; percent carries bps; keep_deposit carries nothing.

object
kind
required
string
Allowed values: none flat percent keep_deposit
minor
integer format: int64
currency
string
Allowed values: USD
bps
integer
<= 10000
fee

none as the inner fee of a fee outcome means “use the policy’s own fee”. flat carries minor + currency; percent carries bps; keep_deposit carries nothing.

object
kind
required
string
Allowed values: none flat percent keep_deposit
minor
integer format: int64
currency
string
Allowed values: USD
bps
integer
<= 10000
refund_as
required
object
kind
required
string
Allowed values: money credit
expires_days
integer
governed_by
required
string
Allowed values: merchant ota

Example 

{
  "status": "created",
  "source": "snapshot",
  "snapshot": {
    "basis": "documents",
    "policy_refs": [
      {
        "scope_kind": "tenant"
      }
    ]
  },
  "policy": {
    "cancel": {
      "below": {
        "kind": "refund_all",
        "fee": {
          "kind": "none",
          "currency": "USD"
        }
      }
    },
    "reschedule": {
      "tiers": [
        {
          "outcome": {
            "kind": "refund_all",
            "fee": {
              "kind": "none",
              "currency": "USD"
            }
          }
        }
      ],
      "below": {
        "kind": "refund_all",
        "fee": {
          "kind": "none",
          "currency": "USD"
        }
      }
    },
    "fee": {
      "kind": "none",
      "currency": "USD"
    },
    "refund_as": {
      "kind": "money"
    },
    "weather": {
      "kind": "none",
      "outcome": "full_refund_or_rebook"
    },
    "no_show": {
      "kind": "refund_all",
      "fee": {
        "kind": "none",
        "currency": "USD"
      }
    },
    "operator_cancel": "refund_all",
    "overrides": {
      "waiver_reasons": [
        "hardship"
      ]
    }
  },
  "now": {
    "cancel": {
      "outcome": {
        "kind": "refund_all",
        "fee": {
          "kind": "none",
          "currency": "USD"
        }
      },
      "fee": {
        "kind": "none",
        "currency": "USD"
      },
      "refund_as": {
        "kind": "money"
      },
      "governed_by": "merchant"
    },
    "reschedule": {
      "outcome": {
        "kind": "refund_all",
        "fee": {
          "kind": "none",
          "currency": "USD"
        }
      },
      "fee": {
        "kind": "none",
        "currency": "USD"
      },
      "refund_as": {
        "kind": "money"
      },
      "governed_by": "merchant"
    }
  }
}

404

Section titled “404”

Unknown booking, or a booking the caller does not own.

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"
}