Renew the current checkout session's selection hold

Re-lock the session's already-held fare with the provider and return a fresh selectionHoldExpiresAt for the SAME fare, along with the new total, the previous total, and whether the price changed. Lets a countdown-driven client (e.g. the payment screen) get a new hold automatically when the old one reaches zero, instead of sending the traveler back to search.

Renewal does not reprice an existing booking. It updates the session's hold expiry, price snapshot and lockedSelectionId; a booking already created for this session is neither repriced nor rebound to the renewed fare. When the renewal moves the held fare or its price, that booking is superseded: POST /v1/{vertical}/bookings/{booking_id}/confirm rejects it with 409 BOOKING_FARE_SUPERSEDED and charges nothing, and it is abandoned rather than voided.

Renewed fare id: renewedFareId is the public id of the re-locked selection (flight fare, stay rate, train fare, or car rate), in the same id space as lockedSelectionId, and session.lockedSelectionId equals it after the renewal (it is unchanged when the provider returned the same id). To pay the renewed newTotal after a 409 SELECTION_HOLD_EXPIRED on confirm: renew, let the traveler accept newTotal when priceChanged, create a new booking with POST /v1/{vertical}/bookings using renewedFareId as the fare id (it replaces the superseded booking as the session's bookingId), and confirm the new booking. An idempotent replay returns the same renewedFareId.

Vertical coverage: every checkout vertical (flight, stay, train, car). The renewal re-locks the SAME offer: the same flight fare, stay rate, train fare, or car rate. When the provider can no longer lock it at any price, the call returns 410 OFFER_EXPIRED (recoveryAction CHANGE_SELECTION) and holds nothing: send the traveler back to results. That is distinct from a price move, which succeeds with priceChanged: true.

The Idempotency-Key header is required, matching the confirm endpoint's convention. Only the MOST RECENT key is remembered: replaying it again returns the original result and does not create a second hold. A different key always starts a fresh renewal, even if an earlier key on this session is still outstanding.

Retrying after a failure. When a renewal fails (any non-2xx response, a dropped connection, or a request that died mid-flight), retry with the SAME Idempotency-Key: the failed attempt's claim never blocks it, and the retry runs a fresh renewal. Do not rotate the key to retry, because a different key always starts a fresh provider re-lock. If the failed attempt could not release its claim, a retry reaching the same server instance still proceeds at once, and a retry reaching another instance proceeds once the claim has aged 120 seconds; until then it gets 409 and can be retried again. Two concurrent requests with the same key never both re-lock the fare: the later one gets 409 while the first is in flight. Replaying a key whose renewal already succeeded returns the stored result.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Headers

Client-generated idempotency key (UUID v4 recommended). Required so a retried renewal request never re-locks the fare a second time; replaying the same key returns the original result verbatim. Keep the same key when retrying after a failed renewal.

Responses

401

Missing or invalid authentication

404

Checkout session not found

409

The session cannot be renewed: nothing is held, the session is 'booked' / 'expired', a confirm is in flight for its booking, another request with the same Idempotency-Key is renewing right now, or the replayed Idempotency-Key belongs to a renewal recorded before renewedFareId existed (renew again with a new key)

410

OFFER_EXPIRED — the held selection can no longer be locked at any price

422

Missing Idempotency-Key header

503

Database, cache, or provider unavailable

Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json