Skip to main content
POST
Refund or void a booked flight (every ticket on the item) against a quote the customer accepted
Start the operation the preview described, a refund, or a void of the original charge, whichever the preview reported as operation_kind. The body is the quote handle and the acknowledged figure PLUS the same auth mode the preview took: 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 your figure differs from the still-live quote’s refund, the call is refused with 409 quote_drift. retry_quote_id 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 sent to the airline. A MANUAL_REQUIRED quote needs manual_ok: true: the operation is then raised for a Jinko agent and answers attention_required with reason: manual_required, again without the airline being called. Committing one without the flag is refused 409 manual_required. That submission is also the one case where acknowledged may be left out: a MANUAL_REQUIRED quote whose penalty is unknown carries no refund to acknowledge, and there is nothing to compare against. Whenever the preview DID name a refund, send it. The other refusals are 409 QUOTE_EXPIRED (preview again), active_operation_exists (poll the active_operation when present instead of starting a second one), not_cancellable, funds_unavailable, superseded, and, when the preview already said commitable: false and you committed anyway, that quote’s own reason answered back as the code: penalty_exceeds_sell or multi_currency_basis. Success does NOT mean the money has moved: giving the tickets back at the airline and returning the money to the customer are separate steps, so the answer is an operation handle to poll with POST /v1/flight_refund_status.

Authorizations

X-API-Key
string
header
required

Body

application/json
quote_id
string
required

The quote_id from a preceding POST /v1/flight_refund_preview. Binds this commit to the figures that quote reported.

Example:

"svq_01J7ZR3M8FKX2P9C"

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_reference
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
intent
object
acknowledged
object

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. REQUIRED whenever the preview carried a refund, which is every quote that names a figure. It may be omitted in exactly one case: a MANUAL_REQUIRED quote that carries no refund at all because the penalty is unknown (penalty.fee_known: false), submitted with manual_ok: true — there is no figure to acknowledge, and inventing one would have the customer agree to a number nobody computed. Omitting it anywhere else is refused by the platform, not here. When present, 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. retry_quote_id 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 sent to the airline.

manual_ok
boolean

Send true to submit a quote whose support_level is MANUAL_REQUIRED. The operation is then raised for a Jinko agent and answers state: attention_required with reason: manual_required — NOTHING is sent to the airline by this call, and the agent settles or fails it. Without the flag such a commit is refused 409 manual_required, so a customer is never put in an agent queue unasked. On an AUTO or AUTO_VOID quote the flag changes nothing. This is also the one submission that may carry no acknowledged figure — when the quote itself named none, because the penalty is unknown.

Example:

false

Response

The refund or void was accepted and is running

operation
string

The operation this call started ("svc_…"). Poll it with POST /v1/flight_refund_status; it is the only handle that reports how the airline 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
reason
string

Why the operation is parked, when state is attention_required. On a commit that is manual_required: you sent manual_ok: true, a Jinko agent now has it, and nothing has been sent to the airline. Not a failure — poll the operation.

Example:

"manual_required"