> ## Documentation Index > Fetch the complete documentation index at: https://docs.dev.gojinko.com/llms.txt > Use this file to discover all available pages before exploring further. # hotel-cancel-status > Check how a hotel cancellation ended 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. ## OpenAPI ````yaml api-reference/public-api.yaml POST /v1/hotel_cancel_status openapi: 3.0.0 info: title: Jinko Public API version: 0.5.0 description: >- Curated public REST surface for Jinko. Authenticated with jnk_ API keys. See https://docs.gojinko.com for guides. ### Per-end-user attribution On booking calls you may send an optional `X-End-User-Id` request header to attribute the booking to one of your own end users (for per-end-user attribution and rate-limiting). The value is an **opaque, tenant-scoped** identifier that you choose — not a Jinko account id. Omit it to book as the tenant. WorkOS-shaped values (prefixed `user_` or `org_`) are rejected. servers: [] security: [] paths: /v1/hotel_cancel_status: post: tags: - Post-booking summary: Check how a hotel cancellation ended description: >- 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. requestBody: content: application/json: schema: $ref: '#/components/schemas/HotelCancelStatusRequest' responses: '200': description: Where the cancellation has got to content: application/json: schema: $ref: '#/components/schemas/HotelCancelStatusResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: BAD_REQUEST message: Malformed JSON in request body. doc_url: https://docs.gojinko.com/concepts/errors '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: AUTH_REQUIRED message: Invalid or expired API key. doc_url: https://docs.gojinko.com/api-reference/authentication '402': description: Payment required — organization balance exhausted content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: PAYMENT_REQUIRED message: >- Insufficient balance — this call costs $0.0150 and your organization has $0.0000 available. Top up at https://dashboard.gojinko.com/developers/billing/topup doc_url: https://docs.gojinko.com/concepts/errors '404': description: Unknown operation or booking, or one this credential may not read. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: booking not found '409': description: The operation conflicts with the current state of the resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: CONFLICT message: an exchange is already in progress for this booking doc_url: https://docs.gojinko.com/concepts/errors '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: BAD_REQUEST message: >- origins: origins is required; trip_type: trip_type is required doc_url: https://docs.gojinko.com/concepts/errors '429': description: Rate limit or quota exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: RATE_LIMITED message: Rate limit or quota exceeded. doc_url: https://docs.gojinko.com/concepts/errors '502': description: The travel provider rejected the request, or an upstream call failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_REJECTED message: >- sabre-rest BargainFinderMaxRQ failed with status 400: 27131 - Number of connection locations exceeds maximum allowed doc_url: https://docs.gojinko.com/concepts/errors '503': description: No travel provider can serve the request right now headers: Retry-After: description: >- Seconds to wait before retrying, forwarded verbatim from the upstream service. Absent when the upstream named no interval. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_UNAVAILABLE message: >- All flight providers are temporarily unable to serve this search. Please retry later. Provider reasons: sabre-rest: provider temporarily closed; travelfusion: quota exhausted doc_url: https://docs.gojinko.com/concepts/errors '504': description: The travel provider did not answer in time content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_TIMEOUT message: sabre-rest BargainFinderMaxRQ timed out after 30s doc_url: https://docs.gojinko.com/concepts/errors security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: HotelCancelStatusRequest: type: object properties: provider_reference: type: string description: >- The supplier's own booking reference. OWNER mode: beyond the API authentication every call needs, this one requires a credential that OWNS the booking — a tenant-bound key reaches its whole tenant, any other credential must belong to the booking's own user. Mutually exclusive with booking_ref + last_name; sending both is rejected with 422. An unknown reference, another tenant's booking and another user's booking are all answered identically, so this field cannot be used to discover which supplier references exist. example: NUITEE-88231 booking_ref: type: string description: >- The Jinko reference. GUEST mode: pair it with last_name and the pair identifies the booking on its own — API authentication is still required, as on every call here, but the credential does not have to own the booking. Mutually exclusive with provider_reference; one without the other is rejected with 422. example: JNK-H1ZK90 last_name: type: string description: >- The lead traveller's surname. Required with booking_ref, and only with it. example: Carrard intent: $ref: '#/components/schemas/IntentInput' operation: type: string description: The "svc_…" handle from a commit, or from POST /v1/hotel_cancel. example: svc_01J7ZR5Q2KME8V4T required: - operation example: booking_ref: JNK-H1ZK90 last_name: Carrard operation: svc_01J7ZR5Q2KME8V4T HotelCancelStatusResponse: type: object properties: operation: type: string example: svc_01J7ZR5Q2KME8V4T state: $ref: '#/components/schemas/ServicingState' reason: type: string description: >- Why the operation is stalled. Present with `state: attention_required`; the value names what Jinko has to resolve, and needs nothing from the caller. example: settlement_review provider: type: object properties: state: type: string description: >- The supplier's own view of the booking: `confirmed` (still standing), `cancelled`, or `pending` (the supplier has not settled it yet). example: cancelled references: type: object properties: booking_id: type: string example: eRR9inUfI cancellation_reference: type: string example: cxl_2f90a1c3 description: >- 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. money: type: object properties: value: type: integer description: >- 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. example: 41250 amount: type: number description: >- 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). currency: type: string description: ISO 4217 currency code. example: USD decimal_places: type: integer description: >- 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. example: 2 direction: type: string description: Which way the money moves. `refund` on a cancellation. example: refund vehicle_state: type: string description: >- 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. example: paid stripe_reference: type: string description: The payment provider's own refund id, once one exists. example: re_3UBIxK2eZvKYlo2C description: >- The refund and where it has got to. Read `vehicle_state` before telling a customer they have been refunded. ErrorResponse: type: object properties: error: type: object properties: code: type: string enum: - AUTH_REQUIRED - PAYMENT_REQUIRED - RATE_LIMITED - BAD_REQUEST - FORBIDDEN - NOT_FOUND - CONFLICT - PRICE_CHANGED - QUOTE_EXPIRED - TRIP_EXPIRED - TRIP_STATE_CONFLICT - OFFER_EXPIRED - OFFER_UNAVAILABLE - MISSING_CUSTOMER_DETAILS - CURRENCY_UNSUPPORTED - UPSTREAM_REJECTED - UPSTREAM_UNAVAILABLE - UPSTREAM_TIMEOUT - UPSTREAM_ERROR - INTERNAL description: >- What went wrong, as a stable machine-readable code. This is a closed set — branch on it rather than on `message`, which is prose and may change. Codes are only ever ADDED, in a minor version, so treat an unknown one as its HTTP status. example: BAD_REQUEST message: type: string doc_url: type: string required: - code - message required: - error IntentInput: type: object properties: user_intent: type: string nullable: true description: >- The user's natural-language intent: the Alpic PII-stripped paraphrase when available, else a best-effort fallback to the client-provided NL query. example: find a cheap flight to Tokyo ServicingState: type: string enum: - in_progress - attention_required - succeeded - failed description: >- 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. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key BearerAuth: type: http scheme: bearer ````