Skip to main content
POST
DEPRECATED — use /v1/hotel_cancel_preview and /v1/hotel_cancel_commit. Cancel a hotel booking and get a refund when eligible. Preview and commit in one call — POST /v1/hotel_cancel_preview plus /v1/hotel_cancel_commit is the two-step form, which shows the customer the refund before anything is cancelled. `refund_amount` is what the CUSTOMER gets back; all amounts are customer-facing only. Returning the money outlives this call: poll the `operation` handle with POST /v1/hotel_cancel_status. Every call here needs API authentication (an API key or a Bearer token); this is about which mode identifies the booking. Call get_booking first, then send booking_ref and the selected booked_item_id. Guests must send last_name; an owning credential may omit 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.
Cancel a hotel booking using the Jinko booking_ref and the hotel’s booked_item_id from get_booking. Omit booked_item_id only when the booking has exactly one hotel item.
  • Guest verification: send booking_ref and last_name together.
  • Authenticated owner: send booking_ref with a credential that owns the booking; last_name may be omitted.

Authorizations

X-API-Key
string
header
required

Body

application/json
booking_ref
string

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

Minimum string length: 1
Example:

"JNK-A0AUR2"

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.

Pattern: ^itm_[a-z2-7]+$(?![\s\S])
Example:

"itm_aaaaaaaaaaaaafhuxsdxpbzrbfz5hm3a"

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"

provider_booking_id
string
deprecated

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.

Minimum string length: 1
provider
string
deprecated

Deprecated: omit it. The platform uses the supplier recorded with the booking. Accepted until 2027-04-30; a request that sends it is answered with Deprecation and Sunset headers.

intent
object

Response

Cancel a hotel booking and get a refund when eligible. Preview and commit in one call — POST /v1/hotel_cancel_preview plus /v1/hotel_cancel_commit is the two-step form, which shows the customer the refund before anything is cancelled. refund_amount is what the CUSTOMER gets back; all amounts are customer-facing only. Returning the money outlives this call: poll the operation handle with POST /v1/hotel_cancel_status. Every call here needs API authentication (an API key or a Bearer token); this is about which mode identifies the booking. Call get_booking first, then send booking_ref and the selected booked_item_id. Guests must send last_name; an owning credential may omit 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.

booking_ref
string
Example:

"JNK-A0AUR2"

booking_reference
string
deprecated

Deprecated: use booking_ref instead. Same value.

Example:

"JNK-A0AUR2"

confirmation_number
string
deprecated

Deprecated: read the item’s supplier_references on POST /v1/get_booking, which names who issued each reference. Customer-facing hotel confirmation number, when supplied by the hotel.

status
string
Example:

"cancelled"

operation
string

The cancellation this call started ("svc_…"). Cancelling the booking at the supplier and returning the money are separate steps, so this call answering does not mean both finished — poll the handle with POST /v1/hotel_cancel_status until state is terminal.

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
refund_amount
object

THE CUSTOMER FIGURE: what goes back to the payment method that paid for this booking — what the customer paid for it, less penalty_amount. Up to contract version 0.3.0 this field carried the SUPPLIER's net refund instead, which on a booking sold at a margin is a smaller number. Only customer-facing amounts are published. Absent when no refund was scheduled — absent is not zero.

customer_refund_amount
object
deprecated

Deprecated alias of refund_amount, carrying the same value. It existed because refund_amount used to be the supplier figure; now that refund_amount IS the customer figure the alias is redundant. Read refund_amount — this field is removed in the next contract version.

penalty_amount
object

The cancellation penalty withheld from the customer, on the same basis as refund_amount: what they paid, less this, is what they get back. When unknown, the amount is omitted; a fee_known: false marker may remain.

cancelled_at
string
Example:

"2026-06-01T12:34:56Z"

idempotent
boolean
Example:

false