> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claim the Best Price Guarantee

> Ask for a hotel offer at a lower price found elsewhere

The traveller found the same hotel stay cheaper on another site and wants Jinko's offer at that price. Use it for prompts like "Booking.com shows this room at \$412, can you match it?". Claim with the Jinko offer they compared, the link, the screenshot and the price they saw; the answer is a new offer at that price, or a decline.

> **Tool description (what the LLM sees)**
>
> ```text theme={null}
> Best Price Guarantee: makes a claim, asks for a Jinko hotel offer at a lower price the traveller found on another site. Nothing is booked or charged.
>
> WHEN TO USE:
> - The traveller compared a Jinko hotel offer with the same stay on another site and found it cheaper there.
> - The traveller has seen a hotel elsewhere and has no Jinko offer yet: run hotel_search first (it can search by hotel name), let them pick the offer, then claim with its trip_item_token.
>
> HOW TO CALL:
> - trip_item_token (the htl_… offer from hotel_search), reference_url, reference_screenshot_url, reference_total, reference_currency.
> - wait_seconds (0-20, default 15) is how long the call waits for the result; most claims are answered within it. A "pending" answer carries the claim's id: read its result with get_best_price_guarantee.
>
> WHAT THE TRAVELLER MUST SUPPLY:
> - The link to the page showing the lower price, the hotel's own page on that site, for the same dates and guests, and, on most accounts, an https address a screenshot of that page can be downloaded from. Both come from the traveller. Never build, guess or reuse one. Jinko opens the link and checks the hotel, the dates, the guests, the room, the board, the cancellation terms and the price.
> - The total they would pay at booking on that page, in the currency of the Jinko offer. Taxes payable at the property are not part of it. A price in another currency is declined, not converted.
>
> WHAT COMES BACK:
> - "offered": a new offer (offer.trip_item_token, starting with htl_neg_) at offer.price_money, valid until offer.expires_at. offer.saving_money is the saving against the rate's current standard price (offer.original.total_money, which can be lower than the price the earlier search showed); 0 means that current price was already at or below the reference.
> - "declined": no offer, with decline.reason, and decline.detail when the check of the reference page found something to explain, pass it on to the traveller. The offer from hotel_search can usually still be booked at its own price.
> - "pending": the review is still running; reading the reference page can take a few minutes. It is not a decline and not a failure, read the result with get_best_price_guarantee; do not tell the traveller it failed.
> - "expired": the offer was not used in time.
>
> BOOKING THE NEW OFFER:
> - Call trip with add_item.trip_item_token = offer.trip_item_token, then checkout, exactly as for any hotel offer.
> - A trip that holds the new offer can hold nothing else. Start a new trip (no trip_id); or, when the trip holds only the offer being replaced, send remove_item for that item and add_item for the new offer in the same trip call. Adding it beside another item is refused.
> - The price at checkout can move with the supplier.
>
> WORDING: this is the price Jinko can offer after its own review. Do not tell the traveller that Jinko negotiated with the hotel or contacted it. A claim can be declined, so do not promise a match before the result says "offered".
> ```

## Parameters

| Name | Type | Required | Description |
| - | - | - | - |
| `trip_item_token` | `string` | Yes | The Jinko hotel offer the traveller compared: an `htl_…` trip\_item\_token from hotel\_search. It names the hotel, the dates, the party and the rate. When the traveller has no Jinko offer yet, run hotel\_search first (it can search by hotel name) and claim with the offer they pick. |
| `reference_url` | `string` | Yes | The https link to the page where the traveller saw the lower price. It must come from the traveller: never build or guess it. |
| `reference_screenshot_url` | `string \| null` | No | An https address a screenshot of that page can be downloaded from, supplied by the traveller. Required on most accounts; a claim without it is then declined with reason `reference_invalid`. |
| `reference_total` | `string` | Yes | The total the traveller would pay AT BOOKING on that page, as a plain decimal string such as "412.50", no currency symbol, no thousands separator. Taxes payable at the property are not part of it. |
| `reference_currency` | `string` | Yes | The ISO 4217 currency of reference\_total. It must be the currency of the Jinko offer (the currency of the offer's price in hotel\_search); a price in another currency is declined, not converted. |
| `wait_seconds` | `integer` | No | How long this call waits for the result before answering, 0-20 seconds (default 15). It only decides when the call returns; the review continues either way. |
| `user_intent` | `string` | No | The end user's current request in their own words, e.g. "help me with my travel plans". Pass it as-is when short; otherwise condense the goal and constraints into 1-2 sentences. Strip personal identifiers (names, emails, phone numbers, addresses, payment details), replace them with placeholders like "\[name]". Optional. Jinko uses it to understand demand, and hotel\_search uses it to rank hotel results against what the user asked for (e.g. "quiet, with a gym, near Times Square"), so keep the user's stated preferences in it. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.