Skip to main content
POST
DEPRECATED — use /v1/flight_refund_commit. Initiate a refund for a booked flight
Issue the refund after the user has reviewed the amount and confirmed cancellation. Poll refund status for terminal state.

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"

order_id
string
deprecated

Deprecated: name the booking with booking_ref and booked_item_id from get_booking. Names the booking instead of booking_ref, 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

Initiate a refund for a booked flight

refund_status
enum<string>

The refund's processing status. PENDING and IN_PROGRESS mean it is still running — poll operation. MANUAL_REQUIRED means a Jinko agent has it: raised, parked, NOT failed. UNCONFIRMED means the airline has not settled its answer yet. SUCCEEDED, FAILED and CANCELLED are terminal. state beside it reports the same operation in the platform vocabulary; either is enough to decide whether to keep polling.

Available options:
PENDING,
IN_PROGRESS,
SUCCEEDED,
FAILED,
MANUAL_REQUIRED,
UNCONFIRMED,
CANCELLED
Example:

"IN_PROGRESS"

operation
string

The refund this call started ("svc_…"). Refunding at the airline and returning the money to the customer's card are separate steps, so this call answering does not mean both finished — poll the handle with POST /v1/flight_refund_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
operation_kind
enum<string>

What the platform would do, or did. cancel — refund the ticket under the fare rules, less the penalty. void — the ticket is inside its void window, so it is voided and the original charge is reversed in full, penalty-free. The platform decides from the live state of the documents; the caller cannot ask for one.

Available options:
cancel,
void
refund_amount
object

THE CUSTOMER FIGURE: what goes back to the payment method that paid for this ticket — what they paid, less the penalty, or the whole charge when the ticket was voided (operation_kind: void). All amounts are customer-facing only. Absent is not zero.

refund_reference
string
Example:

"svc_agqsfzamchoagwznss4z3gwobm5tpxx3r4n5tfrngy"

warnings
string[]