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 booking_ref, item_id and last_name the preview took: ownership is re-checked here rather than carried by the handle, so they have 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 your figure differs from the still-live quote’s refund, the call is refused with 409 quote_drift. requote is that same quote’s handle and current.refund its figure. Show it to the customer, then commit again with that handle and figure. Nothing is cancelled. If the supplier’s policy moved since the quote, quote_drift has no requote; preview again. The other refusals are 409 quote_expired (run hotel_cancel_preview again), active_operation_exists (poll the active_operation when present 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
booking_ref
string
required

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

Minimum string length: 1
Example:

"JNK-A0AUR2"

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.amount_money across. Copying the whole refund object, as older integrations do, is still accepted. 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. Any other key, such as display or basis, is ignored. A mismatch against a still-live quote’s refund is answered 409 quote_drift. requote is that same quote’s handle and current.refund its figure. Show it to the customer, then commit again with that handle and figure. Nothing is cancelled.

item_id
integer

Stable booked item ID from get_booking items[].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.

Required range: 0 < x <= 9007199254740991
Example:

42

last_name
string

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

Minimum string length: 1
Example:

"Doe"

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