GOgojinko
Hotels

Best Price Guarantee: ask for a hotel offer at a lower price found elsewhere

Submit a hotel offer from POST /v1/hotel_search with the lower price the traveller found for the same stay on another site: the link, a screenshot address and the total payable at booking, in the currency of the offer. The submission is reviewed in the background and this call answers pending with an id, or the result when wait_seconds let it finish in time. The answer carries the state of the request in status: pending while the review runs, then offered with the new offer, or declined with the reason. A decline is a 200: it is an answer, not a failure of the call. An offered result is a NEW offer id to add to a trip; the submitted offer is left as it was. Jinko enables Best Price Guarantee per account: a key it is not enabled for is answered HTTP 200 status: declined with decline.reason: feature_disabled.

post/v1/best_price_guarantee

Request

  • Base URL
    https://api.gojinko.com
  • URL
    https://api.gojinko.com/v1/best_price_guarantee
  • Auth
    • API key in header X-API-Key
    • or HTTP bearer

Request body

product'hotel' required

The kind of product the request is about. Only hotel exists today.

objective'price_parity'

What is asked for. price_parity (the default, and the only value today) asks for the reference price, nothing lower.

trip_item_tokenstring required

The hotel offer the traveller compared: hotels[].offers[].trip_item_token from POST /v1/hotel_search. It names the hotel, the dates, the party and the rate. An offer is kept for 75 minutes after the search that returned it.

wait_secondsinteger

How long this call waits for the result before answering, 0–20 seconds (default 0: answer at once). It only decides when the call returns; the review continues either way, and a call that waited without a result answers pending.

Example request

{
  "product": "hotel",
  "objective": "price_parity",
  "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
}

Response

The state of the request

idstring

Identifies the request; read its result with GET /v1/best_price_guarantee/{id}. Absent when the submission was declined before being recorded (feature_disabled, an unknown product).

statusstring required

pending: the review is still running — read the request again; this is not a decline. It can take up to a few minutes when the reference page is checked. offered: offer holds the new offer. declined: no offer, see decline.reason. expired: an offer was made and not used before expires_at. Treat any other value as pending.

poll_after_secondsinteger

Present while status is pending: a suggested pause before reading again.

Example response

{
  "id": "ngo_mfrggzdfmztwq2lknnwg23tpob",
  "status": "offered",
  "offer": {
    "trip_item_token": "htl_neg_ogydqmrsgaydamjqgezdgnbvgy",
    "offer_id": "htl_neg_ogydqmrsgaydamjqgezdgnbvgy",
    "price_money": {
      "value": 41250,
      "currency": "USD",
      "decimal_places": 2,
      "display": "USD 412.50"
    },
    "original": {
      "kind": "offer",
      "trip_item_token": "htl_8f3c1d5e9a7b2c40",
      "offer_id": "htl_8f3c1d5e9a7b2c40",
      "total_money": {
        "value": 43780,
        "currency": "USD",
        "decimal_places": 2,
        "display": "USD 437.80"
      }
    },
    "reference": {
      "total_money": {
        "value": 41250,
        "currency": "USD",
        "decimal_places": 2,
        "display": "USD 412.50"
      },
      "verified": true
    },
    "saving_money": {
      "value": 2530,
      "currency": "USD",
      "decimal_places": 2,
      "display": "USD 25.30"
    },
    "expires_at": "2026-10-12T10:30:00Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.