--- title: "Best Price Guarantee: read the result of a request" method: GET path: "/v1/best_price_guarantee/{id}" tags: ["Hotels"] --- # Best Price Guarantee: read the result of a request `GET /v1/best_price_guarantee/{id}` ## Request - Base URL: `https://api.gojinko.com` - URL: `https://api.gojinko.com/v1/best_price_guarantee/{id}` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer Read a request submitted with `POST /v1/best_price_guarantee`. 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. A request of another key's tenant is answered 404, the same as one that does not exist. ## Path parameters - `id` string, required ## Query parameters - `wait_seconds` integer, nullable: How long this call waits for a request that is still pending, 0–20 seconds (default 0). ## Response `200` The state of the request - BestPriceGuaranteeResponse - `id` string: 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). - `status` string, 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_seconds` integer: Present while `status` is `pending`: a suggested pause before reading again. - `offer` BestPriceGuaranteeOffer - `offer_id` string, required: Deprecated: use `trip_item_token` instead. Same value. - `trip_item_token` string, required: The new offer. Pass it as `add_item.trip_item_token` to `POST /v1/trip`, then check out as for any hotel offer. A trip that holds it can hold nothing else: start a new trip, or send `remove_item` for the offer it replaces together with `add_item` in one call. Adding it beside another item is refused with 409. - `price_money` object, required: What the new offer costs, payable at booking: the price matched to the reference. The price at checkout can move with the supplier. - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta). - `currency` string, required: ISO 4217 currency code. - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`. - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`. - `original` object, required: The offer the new one replaces, and its standard price. - `kind` string, required: How the Jinko product was named in the request. `offer`: a hotel search offer, in `trip_item_token`. Other kinds may be added; read the fields that kind names. - `trip_item_token` string: The offer that was submitted. Present when `kind` is `offer`. - `offer_id` string: Deprecated: use `trip_item_token` instead. Same value. - `total_money` object, required: The standard price of the same rate at the time of the review. It can be lower than the price the earlier search showed for the submitted offer: a search for one hotel can price a rate lower than an area search did. - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta). - `currency` string, required: ISO 4217 currency code. - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`. - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`. - `reference` object, required: The reference the offer was reviewed against. - `total_money` object, required: The reference price as submitted. - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta). - `currency` string, required: ISO 4217 currency code. - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`. - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`. - `verified` boolean, required: `true` when Jinko read the reference page and it showed the same stay at or under the submitted total. - `saving_money` object, required: `original.total_money` minus `price_money`: the saving against the current standard price. Zero when that price was already at or below the reference. - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta). - `currency` string, required: ISO 4217 currency code. - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`. - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`. - `expires_at` string, required: Until when the new offer can be added to a trip (RFC 3339, UTC). At most 30 minutes after the review. - `decline` object: Present when `status` is `declined`. - `reason` string, required: Why there is no offer. The reasons known today are listed here; the set grows, so treat a reason that is not listed as "no offer". `feature_disabled`: Best Price Guarantee is not enabled for this key. `product_not_found`: the offer is not known, 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 could not be found again — search again and resubmit. `reference_source_not_allowed`, `reference_invalid`, `currency_mismatch`: the reference cannot be used as submitted. `price_cannot_be_matched`: this price cannot be offered for this rate. `reference_not_lower`: the current price of this rate is already at or below the reference. After either of these two, search the hotel alone (`hotel_ids`) to get its current price: it can be lower than the price the earlier search showed. `objective_not_supported`: the requested objective is not available. `temporarily_unavailable`, `timeout`: the review did not complete — submitting again may succeed. Reasons from the check of the reference page, each with a specific `decline.detail`: `hotel_mismatch`: the page is for another hotel; `stay_mismatch`: the link or the page is for other dates or another number of guests, so it cannot be compared; `conditions_mismatch`: the page sells the stay only with another room, board or cancellation terms; `reference_mismatch`: the page shows a higher total for the stay than the reference submitted. - `detail` string: What the check of the reference page found, when the decline comes from it. Written for the traveller: pass it on as it is. ## Other responses - `400`: Bad request - `401`: Authentication required - `402`: Payment required — organization balance exhausted - `404`: Resource not found - `409`: The operation conflicts with the current state of the resource - `410`: The resource this request names no longer exists - `422`: Validation error - `429`: Rate limit or quota exceeded - `502`: The travel provider rejected the request, or an upstream call failed - `503`: No travel provider can serve the request right now - `504`: The travel provider did not answer in time --- [API](https://skmtc.dev/gojinko/apis/jinko-public-api.md) - [All operations](https://skmtc.dev/gojinko/apis/jinko-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gojinko/apis/jinko-public-api/revisions/ac5046767e4c?raw)