---
title: "Check how a hotel cancellation ended"
method: POST
path: "/v1/hotel_cancel_status"
tags: ["Post-booking"]
---

# Check how a hotel cancellation ended

`POST /v1/hotel_cancel_status`

## Request

- Base URL: `https://api.gojinko.com`
- URL: `https://api.gojinko.com/v1/hotel_cancel_status`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Report where one cancellation has got to, named by the `operation` handle a commit (or POST /v1/hotel_cancel) returned. Read-only. `state` is the platform view — keep polling while it is `in_progress` or `attention_required`, both of which mean the operation is still alive. `provider` is what the supplier says about the booking and `money` is where the refund itself has got to; the two move independently, so a booking can read `cancelled` while the money is still in flight. Do not tell a customer they have been refunded until `money.vehicle_state` says `paid`. Same auth modes as hotel_cancel_preview.

## Request body

- HotelCancelStatusRequest
  - `booking_ref` string: Jinko booking reference. Call get_booking first, then select its booked_item_id for servicing.
  - `booked_item_id` string: 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_name` string: Required for guest lookup. A credential that owns the booking may omit it; ownership is checked by the platform.
  - `provider_reference` string: 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.
  - `intent` IntentInput
    - `user_intent` string, nullable: The user's natural-language intent: the Alpic PII-stripped paraphrase when available, else a best-effort fallback to the client-provided NL query.
  - `operation` string, required: The "svc_…" handle from a commit, or from POST /v1/hotel_cancel.

## Response `200`

Where the cancellation has got to

- HotelCancelStatusResponse
  - `operation` string
  - `state` 'in_progress' | 'attention_required' | 'succeeded' | 'failed': Where the cancellation has got to. `in_progress` — running; keep polling. `attention_required` — stalled on something a person at Jinko has to resolve (`reason` names it); keep polling, and do not report it to the customer as a failure, because the booking may already be cancelled at the supplier. `succeeded` and `failed` are terminal: the supplier outcome and the money are both settled and nothing further will change.
  - `reason` string: With `state: attention_required`, why the operation is stalled: the value names what Jinko has to resolve, and needs nothing from the caller. With `state: failed`, why it ended: `provider_refused` (the supplier refused before changing anything), `provider_did_not_apply` (the supplier’s record shows it was not applied), `not_sent` (it ended before anything was sent to the supplier), `QUOTE_EXPIRED` (the quote it was committed on no longer stood), `superseded` or `not_cancellable`. Absent on a failed operation that recorded none.
  - `message` string: A sentence about why a failed operation ended, where there is one: what the supplier’s refusal means, or that its price changed after the quote. Present only with `state: failed`; it never states the supplier’s figures.
  - `park_deadline` string: When a parked operation stops waiting for Jinko and is settled or failed. Present with `state: attention_required`; it is how long "keep polling" lasts.
  - `next_run_at` string: When the platform next drives this operation by itself. Informational — polling sooner does not make it run sooner.
  - `provider` object: The supplier's record. It can say `cancelled` while the money is still moving — that is the normal middle of a cancellation, not a discrepancy.
    - `state` string: The supplier's own view of the booking: `confirmed` (still standing), `cancelled`, or `pending` (the supplier has not settled it yet).
    - `references` object
      - `cancellation_reference` string: The reference the supplier issued for the cancellation or refund itself, for example the ticket number a void settles or the supplier’s refund id. It is never the supplier’s identifier for the booking, and is absent when the supplier issued none.
  - `money` object: The refund and where it has got to. Read `vehicle_state` before telling a customer they have been refunded.
    - `amount` number: Deprecated: use `amount_money` instead. Alternative to `value` on some endpoints (the two never appear together); its scale depends on decimal_places. When this object carries decimal_places, amount is an INTEGER in minor units — divide by 10 ** decimal_places (e.g. select_ancillaries total_with_ancillaries). When there is no decimal_places field, amount is a decimal in MAJOR units, safe to display as-is (e.g. trip and checkout totals).
    - `value` integer: Deprecated: use `amount_money` instead. Integer amount in MINOR units, always paired with decimal_places — divide by 10 ** decimal_places to display. Example: value 15977 with decimal_places 2 is 159.77 USD. Rendering this field directly shows prices 100x too high for 2-decimal currencies.
    - `currency` string: Deprecated: use `amount_money` instead. ISO 4217 currency code.
    - `decimal_places` integer: Deprecated: use `amount_money` instead. Scale of the integer value/amount: display = integer / 10 ** decimal_places. Always sent alongside minor-unit amounts. Usually the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry a different scale — ALWAYS use the decimal_places sent with the amount, never a hardcoded 2. Only if the field is genuinely absent on a value-shaped object, fall back to the ISO digits for the currency.
    - `display` string: Deprecated: use `amount_money` instead. The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously.
    - `amount_money` object: The figure being moved.
      - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta).
      - `currency` string, required: ISO 4217 currency code.
      - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`.
      - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`.
    - `direction` string: Which way the money moves. `refund` on a cancellation.
    - `vehicle_state` string: How far the money itself has got, independently of the supplier: `reserved` (earmarked, nothing sent), `refund_pending` (submitted to the payment provider), `payout_initiated` and `payout_settled` (paid out to a third party), `paid` (it has reached the customer), `released` (earmark dropped, nothing owed), `refund_review` (a person at Jinko has to release it). Only `paid` and `payout_settled` mean the customer has the money.
    - `stripe_reference` string: Deprecated. An internal payment reference.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `402`: Payment required — organization balance exhausted
- `404`: Unknown operation or booking, or one this credential may not read.
- `409`: Several booked items match. Select a booked_item_id from items and repeat with booking_ref and booked_item_id.
- `410`: The resource this request names no longer exists
- `422`: Validation error
- `429`: Rate limit or quota exceeded
- `502`: The travel provider rejected the request, or an upstream call failed
- `503`: No travel provider can serve the request right now
- `504`: The travel provider did not answer in time

---

[API](https://skmtc.dev/gojinko/apis/jinko-public-api.md) - [All operations](https://skmtc.dev/gojinko/apis/jinko-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gojinko/apis/jinko-public-api/revisions/ac5046767e4c?raw)