Skip to main content
POST
Cancel a hotel booking against a quote the customer accepted
Start the cancellation the preview described. The body is the quote handle and the acknowledged figure PLUS the same auth mode the preview took, booking_ref + last_name, or provider_reference: ownership is re-checked here rather than carried by the handle, so the mode has to be sent again. acknowledged is the refund the customer was shown, copied from the preview as it arrived (value and decimal_places included): if the refund has moved since the preview, the call is refused with 409 quote_drift, carrying a fresh requote handle and the current figure, and nothing is cancelled, so nobody is cancelled into a number they never saw. The other refusals are 409 quote_expired (run hotel_cancel_preview again), active_operation_exists (poll the active_operation it names instead of starting a second one), not_cancellable and funds_unavailable. Success does NOT mean the money has moved: cancelling at the supplier and refunding the customer are separate steps, so the answer is an operation handle to poll with POST /v1/hotel_cancel_status.

Authorizations

X-API-Key
string
header
required

Body

application/json
quote
string
required

The "svq_…" handle from a preceding POST /v1/hotel_cancel_preview. Binds this commit to the figures that quote reported.

Example:

"svq_01J7ZR3M8FKX2P9C"

acknowledged
object
required

The refund the customer was shown — copy the preview's refund object across. All three of value (minor units), currency and decimal_places are REQUIRED: the platform compares this against the refund as it stands, and a figure whose scale is unstated cannot be compared. amount is not accepted in its place. Anything else on the preview's refund, such as basis, is ignored. A mismatch against the current refund is answered 409 quote_drift, carrying a fresh requote handle and the current figure, and nothing is cancelled.

provider_reference
string

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
string

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
string

The lead traveller's surname. Required with booking_ref, and only with it.

Example:

"Carrard"

intent
object

Response

The cancellation was accepted and is running

operation
string

The cancellation this call started ("svc_…"). Poll it with POST /v1/hotel_cancel_status; it is the only handle that reports how the supplier call and the refund ended.

Example:

"svc_01J7ZR5Q2KME8V4T"

state
enum<string>

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.

Available options:
in_progress,
attention_required,
succeeded,
failed