A merchant's resolved cancellation and change policy (public,)

GET

/merchants/{merchant_slug}/policy

const url = 'https://quikstik-core.fly.dev/merchants/example/policy?channel=direct';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://quikstik-core.fly.dev/merchants/example/policy?channel=direct'

Public, unauthenticated, resolved by merchant slug like the public content routes. Returns the policy the merchant’s rules resolve to for a product and channel — most specific document wins per rule: a channel document that governs → variant → offering → tenant → the built-in default (refund_all, so an unconfigured merchant never retains money by accident). With no query it is the tenant default for the policy page. Clients never resolve: this is the resolved value.

configured is false when nothing backs the answer (basis: built_in_default) — a default is never served as if the merchant had set it. basis: legacy_schedule means the merchant has only its pre- T-minus schedule (a real, configured schedule). sources lists the documents (scope and version) the answer came from.

200 carries Cache-Control: public, max-age=300. 404 unknown merchant; 422 a malformed offering/variant/channel; 503 no backend.

Parameters

Path Parameters

merchant_slug

required

string

Query Parameters

offering

string format: uuid

variant

string format: uuid

channel

string

Allowed values: direct viator getyourguide

Responses

200

The resolved policy

application/json

object

configured

required

boolean

basis

required

string

Allowed values: documents legacy_schedule built_in_default backfill re_resolve

scope

required

object

offering

string format: uuid

nullable

variant

string format: uuid

nullable

channel

string

nullable

Allowed values: direct viator getyourguide

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

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

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

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

sources

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

Example

{
  "basis": "documents",
  "scope": {
    "channel": "direct"
  },
  "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"
      ]
    }
  },
  "sources": [
    {
      "scope_kind": "tenant"
    }
  ]
}

Headers

Cache-Control

string

Always public, max-age=300.

404

Unknown merchant

application/json

object

reason

required

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

string

Example

{
  "reason": "sold_out"
}

422

invalid_offering, invalid_variant or invalid_channel.

application/json

object

reason

required

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

string

Example

{
  "reason": "sold_out"
}

503

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

application/json

object

reason

required

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

string

Example

{
  "reason": "sold_out"
}