flight_search in search mode) on sandbox. It never appears in production, and never in cached search: flight calendar, destination discovery and price monitoring do not return it.
Use the sandbox URLs and a sandbox key, as described in Sandbox keys:
https://api.sandbox.gojinko.com for REST, the SDK and the CLI (--env sandbox), and https://mcp.builders.sandbox.gojinko.com/mcp for the Builder MCP. To pay without a browser, follow the sandbox walkthrough.Find the test airline
Jinko Airline flies both directions of the seven city pairs below, giving 14 routes for the main test scenarios. The separate LHR → MAD scenario route is described after the table. The city codes
NYC, LON and PAR resolve to JFK, LHR and CDG.
One more route, LHR → MAD, exists for a single test: a refund or an exchange that Jinko cannot complete. It is described in A refund or exchange Jinko cannot complete.
Each returned Jinko Airline itinerary is one offer. The full fare ladder has four brands, but a cabin filter can reduce it (see Brands). Do not assert a fixed result count: additional test scenarios can appear. For example, a JFK → LHR search can return 11 offers (44 fares when all four brands are included), including ZZ1101 alongside the ten scenarios documented below. For repeatable booking tests, select a flight from the documented scenarios below and ignore additional scenarios until their behavior is documented.
A round trip always pairs an outbound and a return flight of the same scenario (for example ZZ201 out, ZZ202 back; ZZ1001 out, ZZ1002 back).
On a Jinko Airline segment,
airline and operating_carrier are ZZ and flight_number is the numeric part (101 for ZZ101). To keep only the test airline in the results, send include_carriers: ["ZZ"]: the results are then Jinko Airline only. For a supported future date, when no Jinko Airline itinerary matches the route and other filters you sent (a route it does not fly, or a time window, cabin, stop or price filter that excludes every available flight), the search returns no offers, with result: "no_matches" and an instruction. Read the instruction and adjust one filter.
This example requires curl, Python 3 and JINKO_SANDBOX_KEY set to your sandbox API key. It sets a sample departure date 60 days from today in UTC; replace it with your intended travel date when testing a specific itinerary.
Flights and scenarios
For the seven city pairs above, the flight number isZZ, then the scenario, then one digit for the city pair, then one digit for the direction. Read it from the right:
Scenarios 1 to 9 give three-digit flight numbers (ZZ101 to ZZ962). Later scenarios use four digits: ZZ1001 is scenario 10 and ZZ1101 is scenario 11 on JFK → LHR. The recipes below cover scenarios 1 to 10; additional scenario numbers can appear in search results.
So ZZ101 is JFK → LHR in the normal scenario, ZZ102 is LHR → JFK, ZZ111 is CDG → JFK, ZZ362 is LHR → SIN in the sold-out scenario, and ZZ1001 is JFK → LHR in scenario 10.
Arrival is departure plus block time, in local time at the destination.
What you observe in each scenario
Steps not listed behave as in the normal scenario.Brands
Every flight is sold in four brands. In search results each offer is one flight, and itsfares[] contain the available brands. The full ladder, cheapest first, is ZZ Basic, ZZ Standard, ZZ Flex, ZZ Business. A search with cabin_class: "economy" returns only ZZ Basic, ZZ Standard and ZZ Flex; cabin_class: "business" returns only ZZ Business. Use brand_name to identify the brand and is_refundable, is_changeable and checked_bag_included to compare its policies:
Every brand includes one 7 kg carry-on bag. Fees and penalties are defined in USD and charged once per booking, not per passenger.
Prices
Base fare and tax per adult, one way, in USD:
For each passenger:
- Base = sum of the legs’ base fares × brand factor × passenger factor.
- Tax = sum of the legs’ taxes. It is the same for every passenger, infants included.
All Jinko Airline amounts are defined in USD and rounded to the cent. A search in another
currency returns amounts that Jinko converts from USD at its current exchange rate, so they change from day to day. Search with currency: "USD" when you assert exact amounts.
Example. ZZ Standard, JFK → LHR, one adult:
A round trip adds the two legs: ZZ Basic JFK → LHR → JFK for one adult is (420 + 430) + (180 + 160) = 1190.00 USD.
The checkout total equals the airline total: ZZ101 ZZ Standard checks out at 789.00 USD.
Extra bags
Jinko Airline sells extra bags on every flight and brand. After the trip is quoted, list them withGET /v1/trip/{trip_id}/ancillaries (or read items[].available_ancillaries on the trip). While the trip is still being priced that call answers HTTP 202 with status: "pricing"; poll the same URL after Retry-After until it answers 200. Select with POST /v1/select_ancillaries. Each call replaces the item’s whole selection, so send every extra you want in the same call; a second call with only one bag drops the other. A bag selection is {offer_id, traveler_ref, quantity: 1}, with traveler_ref copied from the trip response. The selection response’s total_with_ancillaries is the fare plus the selections. Read its value in minor units or show its display.
Use each returned offer_id exactly as received; do not construct it from a label or segment.
Each bag can be selected once per traveler. Labels name the journey (“Extra bag 23 kg (outbound)”) so the two bags of a round trip are told apart.
After ticketing, paid bags are issued on their own documents, EMDs whose numbers start with
999, separate from the ticket. What happens next:
- A selection the airline cannot honor never stops the booking. Example: a second unit of the same bag. The flight is booked and ticketed; that extra alone is marked failed with the airline’s reason.
- Oversize bag: the ticket is issued and the bag has
status: "failed"; read itsfailure_reasonfor the explanation. - Void of the booking (ZZ Standard or ZZ Business within 24 hours): the bag EMDs are voided with the tickets and their charges come back with the flight charge. On the refund preview every EMD document carries
recoverable: trueand the quote carriesancillary_recoverable: true; after commit each EMD readsVOIDED. This is the agency void of a whole order: a void that does not cover every ticket and EMD of the booking is not offered. - Refund of the booking (ZZ Flex, or ZZ Business after 24 hours): the flight is refunded; bags are not. The preview marks each bag EMD
recoverable: falseand the quoteancillary_recoverable: false; the EMDs stayACTIVE, and the refund excludes what was paid for them. - Exchange: bags move to the new booking with the same EMD numbers.
Seats
Jinko Airline sells no seat selection: its flights have no seat map, and their catalog lists noseat offer. To test seat selection in sandbox, use a real airline’s flight, for example American Airlines (AA) from LAX to JFK. Real-airline inventory in sandbox is limited and can change.
- Quote the trip and list its ancillaries as for bags. The flight’s
seatoffer can arrive before its map, withseat_map_status: "pending"and no seats. - Read the ancillaries again until
seat_map_statusis"ready". The map then lists the seats you can choose, free and paid. - Select one seat per traveler per flight with
{offer_id, traveler_ref, segment_ref_ids, seat_number, quantity: 1}:seat_numberis a seat ofseat_map.seatswithavailable: true, andsegment_ref_idsis the offer’s one segment. Send it in the samePOST /v1/select_ancillariescall as the bags you keep. - Check out again: the checkout total includes the seat.
booked_ancillaries, as in production: it can stay pending after the flight is ticketed before it reads confirmed or failed. See Seats for the outcomes and charges.
Refund, void and exchange
Start every servicing flow withget_booking, then follow the refund flow or the exchange flow. Tickets are issued right after payment, so a new booking is inside its 24-hour void window.
Refund and void
What you see on the refund calls:
In the preview,
refund and penalty are objects: read the exact figure from refund.amount_money.value and penalty.amount_money.value, integers in minor units (1002.00 USD is value: 100200 with decimal_places: 2).
A void retires the bag EMDs with the tickets and returns their charges with the flight charge. A refund leaves paid bag EMDs active and does not return their price (see Extra bags above).
You cannot ask for a void or a refund: the platform picks the one the table gives. ZZ Business inside 24 hours is voided, not refunded.
Exchange
Exchange shop offers the booked flight number on the new date(s), once per brand. It leaves out the booked brand on the booked dates, because that would change nothing. ZZ Basic and ZZ7xx bookings getsupport_level: "UNSUPPORTED" with reason_code: "NOT_EXCHANGEABLE" and the fixed reason “This booking cannot be exchanged online. Contact Jinko support.”.
get_booking reports the same before you shop: on a ZZ7xx booking can_exchange is false and exchange_support_level is "UNSUPPORTED"; on an exchangeable brand they are true and "AUTO".
POST /v1/exchange_price returns payment_outcome and, in customer_amounts, the customer’s figures: original_fare (the booked brand’s fare), new_fare (the new brand’s fare), penalty_amount (the change fee), total_due (what is charged), non_refundable_difference (the price difference the exchange does not pay back when the new brand costs less, present only when there is one), and residual_value (the part of the original fare the airline keeps as a credit in the traveller’s name after an exchange to a cheaper fare, present only when the airline reports one; it is not refunded to the card). Read these, not the deprecated top-level fare_difference, original_fare, new_fare and penalty_amount, which are the supplier’s figures. The top-level total_due carries the same amount as customer_amounts.total_due. Both fares are the prices of all passengers; paid extras such as bags and seats are not part of them. The figures in customer_amounts add up (an absent figure counts as 0):
payment_outcome is ADD_COLLECT or EVEN, never REFUND, and total_refund is never above 0.
On the Builder MCP, flight_exchange prints the same figures as Current ticket, New ticket, Change fee, You pay or No payment, and Price difference not refunded, and structuredContent.data.customer_amounts holds them. jinko exchange price prints the API answer, customer_amounts included.
The change fee is the booked brand’s, and it is waived when you keep the same brand. Prices do not depend on the date.
Both outcomes can be priced on sandbox. Committing an
EVEN exchange is tested end to end; committing an ADD_COLLECT exchange is not covered by this guide yet.
One shop on a new date therefore reaches every case. Moving to another date in the same brand is always even. From ZZ Standard or ZZ Flex, a dearer brand means paying more and a cheaper brand means paying the change fee alone. From ZZ Business, which has no change fee, every other brand is even. In each cheaper case non_refundable_difference states what is not paid back.
Examples, JFK → LHR, one adult, USD. The figures below are the members of customer_amounts. They are shown in dollars; on the wire every figure is a money object whose value is in minor units (298.00 is value: 29800).
After commit of an even offer, the exchange is confirmed at once. An offer that collects a difference (
ADD_COLLECT) answers checkout_url and is confirmed only once that payment is made. new_ticket_numbers lists new tickets, and the booking’s supplier_references keeps the same airline reference. Keep using the same booking_ref and booked_item_id. A booking that is not ticketed, already refunded, has a refund in progress or was already exchanged cannot be exchanged.
On a ZZ Basic or ZZ7xx booking, exchange shop returns no offers, so there is nothing to price or commit.
ZZ6xx and ZZ7xx
- ZZ6xx, refund needs manual handling. The preview is the brand’s normal answer, so you can commit as usual. The airline accepts the request but a person has to settle it:
flight_refund_statusstays non-terminal, every ticket staysACTIVE, and no money moves. The test airline never settles it. Use it to test that your integration keeps polling and does not tell the customer the refund failed or completed. On sandbox the operation readsstate: "in_progress"for about 20 minutes after commit, thenstate: "attention_required", waiting for a Jinko operator. - ZZ7xx, exchange not permitted. Every brand, ZZ Business included, refuses exchanges: exchange shop answers
support_level: "UNSUPPORTED"withreason_code: "NOT_EXCHANGEABLE". Refunds and voids follow the brand table.
A refund or exchange Jinko cannot complete
Use this route to test what your integration does when Jinko cannot complete a refund or an exchange automatically and the customer has to contact customer support. Search LHR → MAD with these airport codes, in this direction, one-way or round trip. The search returns flight ZZ1381 (return ZZ1382), departing 11:00, in the four brands. MAD → LHR on its own returns no Jinko Airline flights.
Booking, payment and ticketing work as in the normal scenario. After that:
error.message sends the customer to customer support: “This request could not be completed automatically. Please email our customer support team at support.sandbox@gojinko.com; they will complete it for you.” For a partner set up to keep its customers away from Jinko support, error.message names no address: “This request could not be completed automatically and requires manual handling.” On the Builder MCP, flight_refund with action: "preview" and flight_exchange with action: "shop" answer status: "support_required", with the sentence that names the address in error. Every attempt on this booking gets the same answer. The booking and its ticket stay as they are: nothing is cancelled or changed.
Show the message to the customer, and do not retry the request or offer the refund or exchange again. SUPPORT_REQUIRED lists the routes that send this code.
Recipes
Every recipe searches JFK → LHR for one adult in USD, withinclude_carriers: ["ZZ"], on a date from tomorrow, except the last one, which searches LHR → MAD. “Book” means: add the fare’s trip_item_token to a trip with travelers and contact, call checkout, pay (see the sandbox walkthrough), and poll get_trip.
Amounts in the recipes are written in dollars for readability. On the wire every amount is a money object: assert the integer in minor units, from the *_money.value field where the response has one (for example total_amount_money.value 78900 for 789.00 USD), as the Prices and refund sections show.
The asynchronous scenarios (ZZ9xx, ZZ10xx) take about 90 seconds at the airline, plus the interval at which Jinko polls the airline. Allow several minutes before your test gives up.
Normal: book, then refund with a penalty (ZZ101, ZZ Flex)
- Search. Assert the ZZ Flex fare on flight
101costs 1062.00 USD (882.00 + 180.00). - Book. Assert
fulfillment.statusiscompleted. get_booking, thenflight_refund_preview. Assertoperation_kind: "cancel",refund.amount_money.value100200 andpenalty.amount_money.value6000 (USD,decimal_places: 2, so 1002.00 and 60.00).- Commit with the preview’s
refundasacknowledged, then poll status. Assertstate: "succeeded"and every ticketREFUNDED, and keep polling untilmoney.vehicle_stateispaidorpayout_settled: the tickets and the money move independently, and only those two states mean the customer has the money. Sandbox answerspayout_settled.
- Search. Assert the ZZ Standard fare on flight
101costs 789.00 USD. - Book. Assert
fulfillment.statusiscompleted. get_booking, thenflight_refund_preview. Assertoperation_kind: "void",refund.amount_money.value78900 (USD,decimal_places: 2, so 789.00) andpenalty.amount_money.value0.- Commit, then poll status. Assert
state: "succeeded"and every ticketVOIDED, and keep polling untilmoney.vehicle_stateispaidorpayout_settled.
- Search, then price-check the fare. Assert both return 789.00 USD.
- Add to a trip and call
checkout. On the item, assertprice_changed: true,original_price_money.value78900 andprice_money.value86790 (669.90 + 198.00, each 110 % of the search amount). Money fields are objects whosevalueis in minor units (decimal_places: 2for USD). - Assert
price_change.delta_money.valueis 7890 and the checkouttotal_amount_money.valueis 86790. - Pay. Assert
fulfillment.statusiscompleted, charged at 867.90.
- Search, add to a trip, call
checkout. Assert checkout succeeds. - Pay and poll. Assert
fulfillment.statusendsfailedand the customer is not charged.
- Search, add to a trip, call
checkout. Assert checkout succeeds. - Pay and poll. Assert
fulfillment.statusendsfailedand the customer is not charged.
- Book, polling every few seconds.
- Assert
fulfillment.statusstays non-terminal for at least 2 minutes. - Assert it then reaches
completed. Give it up to 5 minutes before failing your test.
- Book.
get_booking, thenflight_refund_preview. Assertoperation_kind: "cancel",refund.amount_money.value100200 andpenalty.amount_money.value6000 (USD,decimal_places: 2, so 1002.00 and 60.00). - Commit with the preview’s
refundasacknowledged. - Poll status. Assert it stays non-terminal and every ticket stays
ACTIVE.
- Book.
get_booking, then exchange shop naming the booked leg with a new date insegments_to_exchange. - Assert
support_level: "UNSUPPORTED",reason_code: "NOT_EXCHANGEABLE"with itsreason, and no offer you can price. flight_refund_previewstill works: assertoperation_kind: "void".
- Search. Assert the ZZ Standard fare on flight
801costs 789.00 USD. - Add to a trip and call
checkout. Assert HTTP 410 witherror.code: "OFFER_EXPIRED". get_trip. Assertquote.status: "failed",quote.failure_reason: "offer_expired", and nofulfillment.
- Book. For about 90 seconds, assert
fulfillment.statusstays non-terminal and the booking’ssupplier_referencesis empty. - Assert
fulfillment.statusthen reachescompletedandsupplier_referencesholds one 6-character airline reference withissuer: "ZZ". get_booking, thenflight_refund_preview. Assertoperation_kind: "void"andrefund.amount_money.value78900 (789.00 USD).- Commit, then poll status. Assert
state: "succeeded"and every ticketVOIDED, and keep polling untilmoney.vehicle_stateispaidorpayout_settled.
- Search, add to a trip, call
checkout. Assert checkout succeeds. - Pay and poll. Assert
fulfillment.statusstays non-terminal for about 90 seconds. - Assert it then ends
failedwith nofailure_reasonand the customer not charged, and thatsupplier_referencesis still empty.
- Book.
get_booking, then exchange shop naming the booked leg with a new date insegments_to_exchange. - Price the ZZ Flex offer. Assert
total_dueis{value: 29800, currency: "USD", decimal_places: 2}, which is 298.00:valueis in minor units. Assertcustomer_amountsadds up:original_fare78900 +total_due29800 =new_fare106200 +penalty_amount2500. - Price the ZZ Basic offer. Assert
payment_outcomeisADD_COLLECT,total_dueis{value: 2500, currency: "USD", decimal_places: 2}, the change fee alone, andcustomer_amounts.non_refundable_differenceis{value: 18900, currency: "USD", decimal_places: 2}: ZZ Basic costs 189.00 less and an exchange does not pay that back. Price the ZZ Standard offer. Assert even. - Commit the ZZ Standard offer, which is even, then poll exchange status. Assert new ticket numbers and the same airline reference in the booking’s
supplier_references. Committing the ZZ Flex offer (ADD_COLLECT) returnscheckout_urlinstead, and the exchange waits for the payment on that page.
- Search, add the ZZ Standard fare, add travelers, then list ancillaries, polling while the call answers 202
pricing. Finddisplay_label: "Extra bag 23 kg (outbound)"withprice_per_unit_money.value: 4000andcurrency: "USD"; keep its returnedoffer_id. - Select it for
pax_1. Asserttotal_with_ancillaries.valueis82900, withcurrency: "USD",decimal_places: 2, anddisplay: "USD 829.00"(789.00 + 40.00). - Book. Assert the charge is 829.00 and the ticket is issued.
- Find
display_label: "Oversize bag 32 kg (outbound)"at 80.00 USD, select its returnedoffer_idforpax_1, and book. - Assert the ticket is issued and the bag has
status: "failed"; read itsfailure_reasonfor the explanation.
- Search LHR → MAD. Select the offer whose
flight_numberis1381, ignoring any other, and assert its ZZ Flex fare costs 286.00 USD. - Book. Assert
fulfillment.statusiscompleted. get_booking. Assert the item’sservicing.can_refundandservicing.can_exchangearefalse.flight_refund_preview. Assert HTTP 409 anderror.code: "SUPPORT_REQUIRED", and thaterror.messagenames the support address, or, for a partner set up to keep its customers away from Jinko support, says that the request requires manual handling.- Exchange shop naming the booked leg (LHR → MAD) with a new date in
segments_to_exchange. Assert HTTP 409 anderror.code: "SUPPORT_REQUIRED".
Limits
- Extras. Jinko Airline sells extra bags but no seat selection; test seats on a real airline (see Extra bags and Seats). Use the returned catalog to check what is available. Included baggage follows the brand.
- Live search only. Flight calendar, destination discovery and price monitoring never return Jinko Airline.
- No same-day departures. Search from tomorrow (UTC). A search for today with
include_carriers: ["ZZ"]returns no offers, and repeating it with the same date will not recover. Choose a date from tomorrow onwards before retrying. - 90-day memory. The test airline forgets a booking’s tickets, refunds and exchanges 90 days after its last change. After that, refunding or exchanging it is refused.
- No reset. Test data is cleared only by that 90-day expiry. Make a new booking for each test run.
