Post-booking

Preview what cancelling a hotel booking would cost

Quote what cancelling would return to the customer right now: the refund, the penalty in force, and the policy behind them. NOTHING is cancelled. refund is the customer figure — what they paid for the item less the penalty. All amounts are customer-facing only. commitable: false means a commit would be refused and not_commitable_reason says why. The handle this returns is named quote: it is what POST /v1/hotel_cancel_commit consumes, and it stops binding at expires_at. Every call here needs API authentication; this is about which mode identifies the booking. Call get_booking first, then send booking_ref and the selected booked_item_id. An owning credential identifies the booking without last_name; guests must supply it. The deprecated provider, order_id, provider_reference and provider_booking_id are accepted until 2027-04-30 where the request declares them; a request that sends one is answered with Deprecation and Sunset headers.

post/v1/hotel_cancel_preview

Request

Base URL
https://api.gojinko.com
URL
https://api.gojinko.com/v1/hotel_cancel_preview
Auth
- API key in header X-API-Key
- or HTTP bearer

Request body

booking_refstring

Jinko booking reference. Call get_booking first, then select its booked_item_id for servicing.

booked_item_idstring

The booked item, from get_booking items[].booked_item_id. Preserved across exchanges. Omit only when the booking has exactly one item of the requested domain; otherwise a 409 returns items to choose from.

last_namestring

Required for guest lookup. A credential that owns the booking may omit it; ownership is checked by the platform.

provider_referencestring

Deprecated: name the booking with booking_ref and booked_item_id from get_booking. Names the booking instead of booking_ref and last_name, never beside it, and needs a credential that owns the booking. Accepted until 2027-04-30; a request that sends it is answered with Deprecation and Sunset headers.

Example request

{
  "booking_ref": "JNK-H1ZK90",
  "last_name": "Doe"
}

Response

What cancelling would cost

quote_idstring

This quote. Pass it as quote_id to POST /v1/hotel_cancel_commit — it binds the commit to the figures below. Opaque; the format may evolve.

quotestring

Deprecated: use quote_id instead. Same value.

statestring

Lifecycle of the QUOTE, not of a cancellation — nothing has been cancelled by this call. completed means the figures are final until expires_at.

commitableboolean

Whether a commit against this quote would be accepted right now. When false, not_commitable_reason says why and committing is pointless.

support_level'AUTO' | 'MANUAL_REQUIRED'

How this cancellation would be carried out. AUTO — the platform completes it end to end. MANUAL_REQUIRED — it is possible, but a Jinko agent has to act; expect a delay rather than an immediate result, and do not treat it as a failure; manual_reason says why. There is no "unsupported" level: a supplier that cannot be cancelled through the API arrives as commitable: false with not_commitable_reason: provider_unsupported, and a booking the supplier will not cancel as it stands arrives as a 409 not_cancellable — from the preview as well as the commit — with error.message “This booking cannot be cancelled online. Contact Jinko support.”

manual_reasonstring

Why a person has to act, in words the customer can be shown. Present with support_level: MANUAL_REQUIRED. Where the reason would be the supplier’s own words, it reads “This request needs manual handling by Jinko support.” not_commitable_reason is the code to branch on; this is the sentence to show.

expires_atstring

When this quote stops binding. Committing after it answers 409 QUOTE_EXPIRED; take a fresh quote and show the customer the new figure before committing again.

booked_item_idstring

The booked item this quote would cancel — the booked_item_id get_booking returns. A booking holding several items is quoted and cancelled one item at a time.

itemstring

Deprecated: use booked_item_id instead. Same value.

not_commitable_reasonstring

Why commitable is false. Today: penalty_exceeds_sell (the penalty is at least what the customer paid), multi_currency_basis (the supplier prices the fee in a currency the customer was not charged in, so no single refund figure exists). A fee the supplier’s policy does not establish (penalty.fee_known: false) is support_level: MANUAL_REQUIRED with no reason code — read manual_reason. Two refusals are never values here: a booking the supplier will not cancel as it stands is 409 not_cancellable from this preview itself, and a supplier with no cancellation route is 422 provider_unsupported. The contract reserves further values (provider_unsupported, funds_unavailable, insufficient_time_to_converge) and new reasons may be added, so treat an unrecognised value as "not right now".

Example response

{
  "quote_id": "svq_01J7ZR3M8FKX2P9C",
  "quote": "svq_01J7ZR3M8FKX2P9C",
  "state": "completed",
  "commitable": true,
  "manual_reason": "the supplier's cancellation policy names no fee in force for this booking, so the fee could not be established",
  "expires_at": "2026-09-03T12:15:00Z",
  "booked_item_id": "itm_7f2c9a4e8b1d",
  "item": "itm_7f2c9a4e8b1d",
  "refund": {
    "value": 41250,
    "currency": "USD",
    "decimal_places": 2,
    "display": "USD 412.50",
    "amount_money": {
      "value": 41250,
      "currency": "USD",
      "decimal_places": 2,
      "display": "USD 412.50"
    },
    "basis": "sell_minus_penalty"
  },
  "penalty": {
    "value": 41250,
    "currency": "USD",
    "decimal_places": 2,
    "display": "USD 412.50",
    "amount_money": {
      "value": 41250,
      "currency": "USD",
      "decimal_places": 2,
      "display": "USD 412.50"
    },
    "fee_known": true
  },
  "policy": {
    "free_cancel_until": "2026-09-01T00:00:00Z",
    "is_refundable_now": true,
    "tiers": [
      {
        "from": "2026-09-01T00:00:00Z",
        "amount": {
          "value": 41250,
          "currency": "USD",
          "decimal_places": 2,
          "display": "USD 412.50"
        },
        "fraction": 0.5
      }
    ]
  },
  "not_commitable_reason": "penalty_exceeds_sell"
}

Changes

No recorded changes to this operation across all 1 revision of this API.