Skip to main content
Sandbox runs against the test systems of real airlines and booking providers. Those systems are often slow, change without notice, and fail for reasons unrelated to your code. A failure path is hard to reach on purpose: you cannot ask a real airline to sell out a seat after payment. Jinko Airline is a fake airline that exists only in sandbox. It always behaves the same way, and each flight number triggers one documented behaviour, so you can test the normal flow and every failure path on demand. It appears only in live flight search (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 is ZZ, 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 its fares[] 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 with GET /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 its failure_reason for 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: true and the quote carries ancillary_recoverable: true; after commit each EMD reads VOIDED. 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: false and the quote ancillary_recoverable: false; the EMDs stay ACTIVE, and the refund excludes what was paid for them.
  • Exchange: bags move to the new booking with the same EMD numbers.
Use the returned catalog to determine which bags are available.

Seats

Jinko Airline sells no seat selection: its flights have no seat map, and their catalog lists no seat 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.
  1. Quote the trip and list its ancillaries as for bags. The flight’s seat offer can arrive before its map, with seat_map_status: "pending" and no seats.
  2. Read the ancillaries again until seat_map_status is "ready". The map then lists the seats you can choose, free and paid.
  3. Select one seat per traveler per flight with {offer_id, traveler_ref, segment_ref_ids, seat_number, quantity: 1}: seat_number is a seat of seat_map.seats with available: true, and segment_ref_ids is the offer’s one segment. Send it in the same POST /v1/select_ancillaries call as the bags you keep.
  4. Check out again: the checkout total includes the seat.
After booking, read each seat’s outcome in 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 with get_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 get support_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):
An exchange does not pay a price difference back. 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_status stays non-terminal, every ticket stays ACTIVE, 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 reads state: "in_progress" for about 20 minutes after commit, then state: "attention_required", waiting for a Jinko operator.
  • ZZ7xx, exchange not permitted. Every brand, ZZ Business included, refuses exchanges: exchange shop answers support_level: "UNSUPPORTED" with reason_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, with include_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)
  1. Search. Assert the ZZ Flex fare on flight 101 costs 1062.00 USD (882.00 + 180.00).
  2. Book. Assert fulfillment.status is completed.
  3. get_booking, then flight_refund_preview. Assert operation_kind: "cancel", refund.amount_money.value 100200 and penalty.amount_money.value 6000 (USD, decimal_places: 2, so 1002.00 and 60.00).
  4. Commit with the preview’s refund as acknowledged, then poll status. Assert state: "succeeded" and every ticket REFUNDED, and keep polling until money.vehicle_state is paid or payout_settled: the tickets and the money move independently, and only those two states mean the customer has the money. Sandbox answers payout_settled.
Void within 24 hours (ZZ101, ZZ Standard)
  1. Search. Assert the ZZ Standard fare on flight 101 costs 789.00 USD.
  2. Book. Assert fulfillment.status is completed.
  3. get_booking, then flight_refund_preview. Assert operation_kind: "void", refund.amount_money.value 78900 (USD, decimal_places: 2, so 789.00) and penalty.amount_money.value 0.
  4. Commit, then poll status. Assert state: "succeeded" and every ticket VOIDED, and keep polling until money.vehicle_state is paid or payout_settled.
Price change (ZZ201, ZZ Standard)
  1. Search, then price-check the fare. Assert both return 789.00 USD.
  2. Add to a trip and call checkout. On the item, assert price_changed: true, original_price_money.value 78900 and price_money.value 86790 (669.90 + 198.00, each 110 % of the search amount). Money fields are objects whose value is in minor units (decimal_places: 2 for USD).
  3. Assert price_change.delta_money.value is 7890 and the checkout total_amount_money.value is 86790.
  4. Pay. Assert fulfillment.status is completed, charged at 867.90.
Sold out after payment (ZZ301, any brand)
  1. Search, add to a trip, call checkout. Assert checkout succeeds.
  2. Pay and poll. Assert fulfillment.status ends failed and the customer is not charged.
Ticketing fails (ZZ401, any brand)
  1. Search, add to a trip, call checkout. Assert checkout succeeds.
  2. Pay and poll. Assert fulfillment.status ends failed and the customer is not charged.
Ticketing delayed (ZZ501, any brand)
  1. Book, polling every few seconds.
  2. Assert fulfillment.status stays non-terminal for at least 2 minutes.
  3. Assert it then reaches completed. Give it up to 5 minutes before failing your test.
Refund needs manual handling (ZZ601, ZZ Flex)
  1. Book. get_booking, then flight_refund_preview. Assert operation_kind: "cancel", refund.amount_money.value 100200 and penalty.amount_money.value 6000 (USD, decimal_places: 2, so 1002.00 and 60.00).
  2. Commit with the preview’s refund as acknowledged.
  3. Poll status. Assert it stays non-terminal and every ticket stays ACTIVE.
Exchange not permitted (ZZ701, ZZ Standard)
  1. Book. get_booking, then exchange shop naming the booked leg with a new date in segments_to_exchange.
  2. Assert support_level: "UNSUPPORTED", reason_code: "NOT_EXCHANGEABLE" with its reason, and no offer you can price.
  3. flight_refund_preview still works: assert operation_kind: "void".
Offer no longer available (ZZ801, ZZ Standard)
  1. Search. Assert the ZZ Standard fare on flight 801 costs 789.00 USD.
  2. Add to a trip and call checkout. Assert HTTP 410 with error.code: "OFFER_EXPIRED".
  3. get_trip. Assert quote.status: "failed", quote.failure_reason: "offer_expired", and no fulfillment.
Asynchronous booking that confirms, then void (ZZ901, ZZ Standard)
  1. Book. For about 90 seconds, assert fulfillment.status stays non-terminal and the booking’s supplier_references is empty.
  2. Assert fulfillment.status then reaches completed and supplier_references holds one 6-character airline reference with issuer: "ZZ".
  3. get_booking, then flight_refund_preview. Assert operation_kind: "void" and refund.amount_money.value 78900 (789.00 USD).
  4. Commit, then poll status. Assert state: "succeeded" and every ticket VOIDED, and keep polling until money.vehicle_state is paid or payout_settled.
Asynchronous booking that fails (ZZ1001, ZZ Standard)
  1. Search, add to a trip, call checkout. Assert checkout succeeds.
  2. Pay and poll. Assert fulfillment.status stays non-terminal for about 90 seconds.
  3. Assert it then ends failed with no failure_reason and the customer not charged, and that supplier_references is still empty.
Exchange with a payment outcome (ZZ101, ZZ Standard)
  1. Book. get_booking, then exchange shop naming the booked leg with a new date in segments_to_exchange.
  2. Price the ZZ Flex offer. Assert total_due is {value: 29800, currency: "USD", decimal_places: 2}, which is 298.00: value is in minor units. Assert customer_amounts adds up: original_fare 78900 + total_due 29800 = new_fare 106200 + penalty_amount 2500.
  3. Price the ZZ Basic offer. Assert payment_outcome is ADD_COLLECT, total_due is {value: 2500, currency: "USD", decimal_places: 2}, the change fee alone, and customer_amounts.non_refundable_difference is {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.
  4. 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) returns checkout_url instead, and the exchange waits for the payment on that page.
Extra bag (ZZ101, ZZ Standard)
  1. Search, add the ZZ Standard fare, add travelers, then list ancillaries, polling while the call answers 202 pricing. Find display_label: "Extra bag 23 kg (outbound)" with price_per_unit_money.value: 4000 and currency: "USD"; keep its returned offer_id.
  2. Select it for pax_1. Assert total_with_ancillaries.value is 82900, with currency: "USD", decimal_places: 2, and display: "USD 829.00" (789.00 + 40.00).
  3. Book. Assert the charge is 829.00 and the ticket is issued.
Oversize bag fails (ZZ101, ZZ Standard)
  1. Find display_label: "Oversize bag 32 kg (outbound)" at 80.00 USD, select its returned offer_id for pax_1, and book.
  2. Assert the ticket is issued and the bag has status: "failed"; read its failure_reason for the explanation.
A refund or exchange Jinko cannot complete (ZZ1381, ZZ Flex)
  1. Search LHR → MAD. Select the offer whose flight_number is 1381, ignoring any other, and assert its ZZ Flex fare costs 286.00 USD.
  2. Book. Assert fulfillment.status is completed.
  3. get_booking. Assert the item’s servicing.can_refund and servicing.can_exchange are false.
  4. flight_refund_preview. Assert HTTP 409 and error.code: "SUPPORT_REQUIRED", and that error.message names the support address, or, for a partner set up to keep its customers away from Jinko support, says that the request requires manual handling.
  5. Exchange shop naming the booked leg (LHR → MAD) with a new date in segments_to_exchange. Assert HTTP 409 and error.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.