Best Price Guarantee

Best Price Guarantee works with every production and sandbox key. On sandbox (https://api.sandbox.gojinko.com, https://mcp.builders.sandbox.gojinko.com/mcp, CLI --env sandbox) Jinko does not open the reference page: an offer comes back with offer.reference.verified false, and the declines that come from checking the link and the page (hotel_mismatch, stay_mismatch, conditions_mismatch, reference_mismatch) are not returned there. Test those on production.

A traveller compares a Jinko hotel offer with the same stay on another site and finds it cheaper there. Best Price Guarantee takes that price, with the link and a screenshot of the page, and answers with a new offer at that price, or with a decline. The new offer is added to a trip and paid like any other hotel offer.

What it covers

Hotels only, and offers for a single room.
Jinko matches its price to a credible reference: the same hotel, room, board and cancellation terms, for the same dates and guests, on a site accepted as a reference.
Jinko opens the link and reads the page: the hotel, the dates and guests, the room, board and cancellation terms, and the total. A page for another hotel, stay or terms, or with a higher total, is declined. Send the link to this hotel’s page on that site, for the same stay as the Jinko offer. offer.reference.verified is true when the page confirmed the reference.
The reference is the total payable at booking on the other site, in the currency of the Jinko offer. Taxes payable at the property are not part of it, and nothing is converted.
A request can be declined. Do not promise the traveller a match before the answer says offered.

Submit the lower price

Start from an offer returned by POST /v1/hotel_search. An offer can be submitted for 75 minutes after the search that returned it.

const api = async (method, path, body) => {
  const response = await fetch(`https://api.gojinko.com/v1/${path}`, {
    method,
    headers: {
      'X-API-Key': process.env.JINKO_API_KEY,
      'Content-Type': 'application/json',
    },
    body: body ? JSON.stringify(body) : undefined,
  })
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`)
  return response.json()
}

const request = await api('POST', 'best_price_guarantee', {
  product: 'hotel',
  trip_item_token: 'htl_8f3c1d5e9a7b2c40',
  reference: {
    url: 'https://www.booking.com/hotel/fr/example.html?checkin=2026-11-10',
    screenshot_url: 'https://files.example.com/screenshots/8f3.png',
    total: '412.50',
    currency: 'USD',
  },
  wait_seconds: 15,
})

The review runs in the background. wait_seconds (0 to 20) is how long the call waits for it; most requests finish within that time. The answer carries an id and a status:

`status`	Meaning
`pending`	The review is still running. Read the request again; this is not a decline. Reading the reference page can take a few minutes.
`offered`	`offer` holds the new offer.
`declined`	No offer. `decline.reason` says why, and `decline.detail` what the page showed when the decline comes from reading it.
`expired`	An offer was made and was not used before `offer.expires_at`.

A decline is answered with HTTP 200: it is an answer, not a failure of the call.

Read the result

const result = await api(
  'GET',
  `best_price_guarantee/${request.id}?wait_seconds=15`
)

An offered result looks like this:

{
  "id": "ngo_mfrggzdfmztwq2lknnwg23tpob",
  "status": "offered",
  "offer": {
    "trip_item_token": "htl_neg_7k2m9q4x8w1e5r3t",
    "price_money": { "value": 41250, "currency": "USD", "decimal_places": 2, "display": "USD 412.50" },
    "original": {
      "kind": "offer",
      "trip_item_token": "htl_8f3c1d5e9a7b2c40",
      "total_money": { "value": 44500, "currency": "USD", "decimal_places": 2, "display": "USD 445.00" }
    },
    "reference": {
      "total_money": { "value": 41250, "currency": "USD", "decimal_places": 2, "display": "USD 412.50" },
      "verified": true
    },
    "saving_money": { "value": 3250, "currency": "USD", "decimal_places": 2, "display": "USD 32.50" },
    "expires_at": "2026-11-01T10:30:00Z"
  }
}

offer.original.total_money is the current standard price of that room, board and cancellation terms. It can be lower than the price the earlier search showed.

When Jinko’s current price is already at or below the reference

There is nothing to match, and the answer is one of two:

offered, with the new offer priced at that current price and saving_money zero. This is the usual answer. Book the new offer as described below.
declined with reference_not_lower. No new offer is made for this rate. Search the hotel alone (hotel_ids) and book the rate at its current price.

Book the new offer

Add offer.trip_item_token to a trip with POST /v1/trip (add_item.trip_item_token), then add the travellers and call POST /v1/checkout, exactly as for any hotel offer. See Hotel booking.

A trip that holds the new offer holds nothing else. Start a new trip for it. Adding it beside another item is refused with HTTP 409.
The new offer is valid for 30 minutes (offer.expires_at).
The total at checkout can move with the hotel’s price. When the price can no longer be offered, checkout answers OFFER_EXPIRED; search and submit again.
Payment, confirmation, cancellation and refund work as for any hotel booking, on the price paid.

When a request is declined

`decline.reason`	What to do
`feature_disabled`	Best Price Guarantee is not enabled for this key.
`product_not_found`	The offer is unknown or older than 75 minutes. Search again.
`product_not_supported`	Not a single-room hotel offer from a search.
`rate_unavailable`	The same room, board and cancellation terms were not found again. Search again and resubmit.
`reference_source_not_allowed`	The link is not on a site accepted as a reference.
`reference_invalid`	The link, the screenshot address or the total cannot be used as submitted.
`currency_mismatch`	The reference is not in the currency of the offer.
`price_cannot_be_matched`	This price cannot be offered for this rate.
`reference_not_lower`	Jinko’s current price is already at or below the reference and no new offer is made. See above.
`objective_not_supported`	The requested `objective` is not available. Omit it, or send `price_parity`.
`temporarily_unavailable`	The review did not complete. Submitting again may succeed.
`timeout`	The review did not complete in time. Submitting again may succeed.
`hotel_mismatch`	The reference page is for another hotel.
`stay_mismatch`	The link or the page is for other dates or another number of guests, so the prices cannot be compared. Ask for a link for the same stay.
`conditions_mismatch`	The page sells this stay only with another room, board or cancellation terms.
`reference_mismatch`	The page shows a higher total for this stay than the reference submitted.

The last four come from reading the reference page, and decline.detail says what the page showed, for example the page shows prices for 1 adult(s); the Jinko offer is for 2. Pass it on to the traveller as it is. The list grows. Treat a reason that is not listed as “no offer”. After price_cannot_be_matched, search that hotel alone (hotel_ids) as well: the price of the same rate there can be lower than the one an area search showed.

With the MCP server

The MCP server serves the same flow as two tools. claim_best_price_guarantee makes the request, with the same fields as POST /v1/best_price_guarantee. get_best_price_guarantee reads its result by the id the claim returned; it never makes a request. Describe the result to the traveller as the price Jinko can offer after its own review.

Getting started

Guides

Marketing claim

Authentication

Connect

Developer Platform

Concepts

What it covers

Submit the lower price

Read the result

When Jinko’s current price is already at or below the reference

Book the new offer

When a request is declined

With the MCP server

​What it covers

​Submit the lower price

​Read the result

​When Jinko’s current price is already at or below the reference

​Book the new offer

​When a request is declined

​With the MCP server

What it covers

Submit the lower price

Read the result

When Jinko’s current price is already at or below the reference

Book the new offer

When a request is declined

With the MCP server