> ## 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. # best-price-guarantee > 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`. ## OpenAPI ````yaml api-reference/public-api.yaml POST /v1/best_price_guarantee openapi: 3.0.0 info: title: Jinko Public API version: 0.87.0 description: >- Curated public REST surface for Jinko. Authenticated with jnk_ API keys. See https://docs.gojinko.com for guides. ### Per-end-user attribution On booking calls you may send an optional `X-End-User-Id` request header to attribute the booking to one of your own end users (for per-end-user attribution and rate-limiting). The value is an **opaque, tenant-scoped** identifier that you choose — not a Jinko account id. Omit it to book as the tenant. Values prefixed `user_` or `org_` are rejected. servers: - url: https://api.gojinko.com description: Production - url: https://api.sandbox.gojinko.com description: Sandbox security: [] paths: /v1/best_price_guarantee: post: tags: - Hotels summary: >- Best Price Guarantee: ask for a hotel offer at a lower price found elsewhere description: >- 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`. requestBody: content: application/json: schema: $ref: '#/components/schemas/BestPriceGuaranteeRequest' responses: '200': description: The state of the request content: application/json: schema: $ref: '#/components/schemas/BestPriceGuaranteeResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: BAD_REQUEST message: Malformed JSON in request body. doc_url: https://docs.gojinko.com/concepts/errors '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: AUTH_REQUIRED message: Invalid or expired API key. doc_url: https://docs.gojinko.com/authentication/api-keys '402': description: Payment required — organization balance exhausted content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: PAYMENT_REQUIRED message: >- Insufficient balance — this call costs $0.0150 and your organization has $0.0000 available. Top up at https://dashboard.gojinko.com/developers/billing/topup doc_url: https://docs.gojinko.com/concepts/errors '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: Resource not found. doc_url: https://docs.gojinko.com/concepts/errors '409': description: The operation conflicts with the current state of the resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: CONFLICT message: >- The operation conflicts with the current state of the resource. doc_url: https://docs.gojinko.com/concepts/errors '410': description: The resource this request names no longer exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: GONE message: The resource no longer exists. doc_url: https://docs.gojinko.com/concepts/errors '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: BAD_REQUEST message: A required field is missing or invalid. doc_url: https://docs.gojinko.com/concepts/errors '429': description: Rate limit or quota exceeded headers: Retry-After: description: >- Seconds to wait before retrying, forwarded verbatim from the upstream service. Absent when the upstream named no interval. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: RATE_LIMITED message: Too many requests. Retry after the Retry-After delay. doc_url: https://docs.gojinko.com/concepts/errors '502': description: The travel provider rejected the request, or an upstream call failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_REJECTED message: The request was declined for this offer. Try another offer. doc_url: https://docs.gojinko.com/concepts/errors '503': description: No travel provider can serve the request right now headers: Retry-After: description: >- Seconds to wait before retrying, forwarded verbatim from the upstream service. Absent when the upstream named no interval. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_UNAVAILABLE message: >- The service is temporarily unavailable. Retry after the Retry-After delay. doc_url: https://docs.gojinko.com/concepts/errors '504': description: The travel provider did not answer in time content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_TIMEOUT message: >- The request timed out before a result was available. Retry the request. doc_url: https://docs.gojinko.com/concepts/errors security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: BestPriceGuaranteeRequest: type: object properties: product: type: string enum: - hotel description: The kind of product the request is about. Only `hotel` exists today. example: hotel objective: type: string enum: - price_parity description: >- What is asked for. `price_parity` (the default, and the only value today) asks for the reference price, nothing lower. example: price_parity trip_item_token: type: string minLength: 1 description: >- 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. example: htl_8f3c1d5e9a7b2c40 reference: $ref: '#/components/schemas/BestPriceGuaranteeReference' wait_seconds: type: integer minimum: 0 maximum: 20 description: >- 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: 15 required: - product - trip_item_token - reference BestPriceGuaranteeResponse: type: object properties: id: type: string description: >- 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). example: ngo_mfrggzdfmztwq2lknnwg23tpob status: type: string description: >- `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`. example: offered poll_after_seconds: type: integer description: >- Present while `status` is `pending`: a suggested pause before reading again. example: 2 offer: $ref: '#/components/schemas/BestPriceGuaranteeOffer' decline: type: object properties: reason: $ref: '#/components/schemas/BestPriceGuaranteeDeclineReason' detail: type: string description: >- What the check of the reference page found, when the decline comes from it. Written for the traveller: pass it on as it is. example: >- the page shows a stay from 2026-11-20 to 2026-11-22; the Jinko offer is from 2026-11-17 to 2026-11-19 required: - reason description: Present when `status` is `declined`. required: - status example: 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' ErrorResponse: type: object properties: error: type: object properties: code: type: string enum: - INVALID_SEGMENTS_TO_EXCHANGE - PARTIAL_EXCHANGE_UNSUPPORTED - LEG_ALREADY_DEPARTED - DEPARTURE_DATE_IN_PAST - LEG_DATES_OUT_OF_ORDER - INVALID_EXCHANGE_REQUEST - NOT_EXCHANGEABLE - CREDENTIAL_FORMAT_INVALID - PAYMENT_TYPE_NOT_ENABLED - PAYMENT_CREDENTIAL_INVALID - TRIP_OWNED_BY_OTHER_PAYMENT - IDEMPOTENCY_KEY_REUSED - ATTEMPT_IN_PROGRESS - ATTEMPT_TERMINAL - TEMPORARILY_UNAVAILABLE - AUTH_REQUIRED - PAYMENT_REQUIRED - RATE_LIMITED - BAD_REQUEST - FORBIDDEN - NOT_FOUND - CONFLICT - GONE - QUOTE_PENDING - QUOTE_EXPIRED - TRIP_EXPIRED - TRIP_STATE_CONFLICT - OFFER_EXPIRED - OFFER_UNAVAILABLE - MISSING_CUSTOMER_DETAILS - INVALID_PHONE_NUMBER - CURRENCY_UNSUPPORTED - HOTEL_NAME_LOW_CONFIDENCE - DESTINATION_LOW_CONFIDENCE - UPSTREAM_REJECTED - UPSTREAM_UNAVAILABLE - UPSTREAM_TIMEOUT - UPSTREAM_ERROR - INTERNAL description: >- What went wrong, as a stable machine-readable code. This is a closed set — branch on it rather than on `message`, which is prose and may change. New codes arrive in a minor version, so treat an unknown one as its HTTP status. A code can also stop being emitted: it leaves this set in a minor version, named in the changelog, and a branch you wrote for it goes unreached rather than wrong. example: BAD_REQUEST message: type: string description: >- What went wrong, in prose. These codes always carry the same message, and it never includes text from a supplier: `RATE_LIMITED` — "Too many requests. Retry after the Retry-After delay."; `OFFER_EXPIRED` — "This offer has expired. Search again."; `OFFER_UNAVAILABLE` — "This offer is no longer available. Search again."; `UPSTREAM_REJECTED` — "The request was declined for this offer. Try another offer."; `UPSTREAM_UNAVAILABLE` — "The service is temporarily unavailable. Retry after the Retry-After delay."; `UPSTREAM_TIMEOUT` — "The request timed out before a result was available. Retry the request."; `UPSTREAM_ERROR` — "The request could not be completed.". doc_url: type: string field: type: string description: >- On a 400 `BAD_REQUEST` that names one refused input: the path of that field in your request, e.g. `selections[1].quantity` for the second selection of a `select_ancillaries` call. Absent when the refusal names no single field. example: selections[1].quantity required: - code - message required: - error BestPriceGuaranteeReference: type: object properties: url: type: string minLength: 1 description: >- The https link to the page where the traveller saw the lower price. It must be on a site accepted as a reference; another site is answered `declined` with reason `reference_source_not_allowed`. example: https://www.booking.com/hotel/fr/example.html?checkin=2026-11-10 screenshot_url: type: string minLength: 1 description: >- An https address a screenshot of that page can be downloaded from. Required on most accounts: a submission without it is then answered `declined` with reason `reference_invalid`. example: https://files.example.com/screenshots/8f3.png total: type: string minLength: 1 description: >- The total payable AT BOOKING on that page, as a plain decimal string: no currency symbol, no thousands separator, at most the decimal places of `currency`. Taxes payable at the property are not part of it. example: '412.50' currency: type: string minLength: 3 maxLength: 3 description: >- The ISO 4217 currency of `total`. It must be the currency of the offer being compared (`total_amount_money.currency` of the offer in `hotel_search`). A price in another currency is answered `declined` with reason `currency_mismatch`; nothing is converted. example: USD required: - url - total - currency BestPriceGuaranteeOffer: type: object properties: offer_id: type: string description: 'Deprecated: use `trip_item_token` instead. Same value.' example: htl_neg_ogydqmrsgaydamjqgezdgnbvgy deprecated: true trip_item_token: type: string description: >- 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. example: htl_neg_ogydqmrsgaydamjqgezdgnbvgy price_money: allOf: - $ref: '#/components/schemas/MoneyValue' - description: >- What the new offer costs, payable at booking: the price matched to the reference. The price at checkout can move with the supplier. original: type: object properties: kind: type: string description: >- 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. example: offer trip_item_token: type: string description: The offer that was submitted. Present when `kind` is `offer`. example: htl_8f3c1d5e9a7b2c40 offer_id: type: string description: 'Deprecated: use `trip_item_token` instead. Same value.' example: htl_8f3c1d5e9a7b2c40 deprecated: true total_money: allOf: - $ref: '#/components/schemas/MoneyValue' - description: >- 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. required: - kind - total_money description: The offer the new one replaces, and its standard price. reference: type: object properties: total_money: allOf: - $ref: '#/components/schemas/MoneyValue' - description: The reference price as submitted. verified: type: boolean description: >- `true` when Jinko read the reference page and it showed the same stay at or under the submitted total. example: true required: - total_money - verified description: The reference the offer was reviewed against. saving_money: allOf: - $ref: '#/components/schemas/MoneyValue' - description: >- `original.total_money` minus `price_money`: the saving against the current standard price. Zero when that price was already at or below the reference. expires_at: type: string description: >- Until when the new offer can be added to a trip (RFC 3339, UTC). At most 30 minutes after the review. example: '2026-10-12T10:30:00Z' required: - offer_id - trip_item_token - price_money - original - reference - saving_money - expires_at BestPriceGuaranteeDeclineReason: type: string description: >- 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. example: price_cannot_be_matched MoneyValue: type: object properties: value: type: integer description: >- 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). example: 41250 currency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217 currency code. example: USD decimal_places: type: integer description: >- The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`. example: 2 display: type: string description: >- 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`. example: USD 412.50 required: - value - currency - decimal_places - display description: >- Money as every new field carries it: `value` is an INTEGER in minor units at the ISO 4217 digits of `currency` (`decimal_places`), and `display` is the same figure ready to show. All four members are always present; a figure the platform does not know is absent, never `{value: 0}`. New integrations read the `*_money` fields (and `value` on the objects that carry it); the two-scale rule described on `Money` applies only to the deprecated fields. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.