> ## Documentation Index > Fetch the complete documentation index at: https://docs.dev.gojinko.com/llms.txt > Use this file to discover all available pages before exploring further. # car-exchange-preview > Preview the rentals a car booking could be exchanged to List the rentals this booking could move to, at the booked times, or at new `pick_up_date_time` / `drop_off_date_time` (branch-local `YYYY-MM-DDTHH:MM:SS`; omit either to keep the booked time), and with the rate extras (child seat, GPS, additional driver, excess cover) the rental should end up with (`ancillaries`; omit to keep what the booking carries, `[]` to remove every extra), each priced in full with that selection and with its `delta` against what was paid. Nothing is changed. Vehicle choice is not an input: every alternative at the requested times comes back as its own offer. The returned `exchange_id` plus one offer's `exchange_offer_token` are what car\_exchange\_commit consumes. A booking that cannot be exchanged (already cancelled, an exchange already in flight) answers 200 with `exchangeable: false` and a `reason`, not an error. Guest-authenticated: booking\_ref + last\_name; a wrong pair returns 404 rather than confirming the booking's existence. ## OpenAPI ````yaml api-reference/public-api.yaml POST /v1/car_exchange_preview openapi: 3.0.0 info: title: Jinko Public API version: 0.5.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. WorkOS-shaped values (prefixed `user_` or `org_`) are rejected. servers: [] security: [] paths: /v1/car_exchange_preview: post: tags: - Cars summary: Preview the rentals a car booking could be exchanged to description: >- List the rentals this booking could move to — at the booked times, or at new `pick_up_date_time` / `drop_off_date_time` (branch-local `YYYY-MM-DDTHH:MM:SS`; omit either to keep the booked time), and with the rate extras (child seat, GPS, additional driver, excess cover) the rental should end up with (`ancillaries`; omit to keep what the booking carries, `[]` to remove every extra) — each priced in full with that selection and with its `delta` against what was paid. Nothing is changed. Vehicle choice is not an input: every alternative at the requested times comes back as its own offer. The returned `exchange_id` plus one offer's `exchange_offer_token` are what car_exchange_commit consumes. A booking that cannot be exchanged (already cancelled, an exchange already in flight) answers 200 with `exchangeable: false` and a `reason`, not an error. Guest-authenticated: booking_ref + last_name; a wrong pair returns 404 rather than confirming the booking's existence. requestBody: content: application/json: schema: $ref: '#/components/schemas/CarExchangePreviewRequest' responses: '200': description: Exchange alternatives with their price deltas content: application/json: schema: $ref: '#/components/schemas/CarExchangePreviewResponse' '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/api-reference/authentication '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: Unknown booking_ref + last_name pair. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: booking not found '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: an exchange is already in progress for this booking 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: >- origins: origins is required; trip_type: trip_type is required doc_url: https://docs.gojinko.com/concepts/errors '429': description: Rate limit or quota exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: RATE_LIMITED message: Rate limit or quota exceeded. 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: >- sabre-rest BargainFinderMaxRQ failed with status 400: 27131 - Number of connection locations exceeds maximum allowed 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: >- All flight providers are temporarily unable to serve this search. Please retry later. Provider reasons: sabre-rest: provider temporarily closed; travelfusion: quota exhausted 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: sabre-rest BargainFinderMaxRQ timed out after 30s doc_url: https://docs.gojinko.com/concepts/errors security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: CarExchangePreviewRequest: type: object properties: booking_ref: type: string minLength: 1 description: Jinko booking reference from the confirmation email. example: JNK-8PT9VS last_name: type: string minLength: 1 description: Lead traveler's last name, exactly as on the booking. example: Carrard intent: $ref: '#/components/schemas/IntentInput' pick_up_date_time: type: string pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$ description: >- New pick-up date-time, branch-local, no timezone. Omit to keep the booked time. example: '2026-09-13T10:00:00' drop_off_date_time: type: string pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$ description: >- New drop-off date-time, branch-local, no timezone. Omit to keep the booked time. example: '2026-09-16T10:00:00' ancillaries: type: array items: $ref: '#/components/schemas/CarExchangeAncillarySelection' description: >- The rate extras (child seat, GPS, additional driver, excess cover) the rental should END UP with. Omit to keep what the booking carries today; send `[]` to remove every extra; send a list to replace the selection. Every offer comes back priced with this selection and echoes it under `rental.ancillaries`. To change only the extras, send this without new times: the current rental returns as an offer and its `delta` settles like any other exchange. A `paid_at: local` extra is selectable but never enters the price. required: - booking_ref - last_name example: booking_ref: JNK-8PT9VS last_name: Carrard pick_up_date_time: '2026-09-13T10:00:00' ancillaries: - offer_id: CHILD_SEAT quantity: 1 CarExchangePreviewResponse: type: object properties: exchange_id: type: string description: >- Opaque reference of this preview ("exc_…"). Pass to car_exchange_commit with the chosen offer token — it binds the commit to the prices quoted here. Absent when the booking is not exchangeable. Treat as an opaque string; the format may evolve. example: exc_7c1e4b9a2d8f4e6b9a3c5d7e1f2a4b6c exchangeable: type: boolean example: true reason: type: string description: >- Why the booking cannot be exchanged (already cancelled, an exchange already in flight). Absent when it can. current: $ref: '#/components/schemas/CarExchangeRental' paid: allOf: - $ref: '#/components/schemas/CarAmount' - description: >- What the customer paid — the basis every `delta` is computed against. Absent when the booking is not exchangeable. offers: type: array items: $ref: '#/components/schemas/CarExchangeOffer' description: >- Replacement candidates at the requested times, each priced in full and with its delta. Empty when nothing is available, or when the booking is not exchangeable. warnings: type: array items: type: string ErrorResponse: type: object properties: error: type: object properties: code: type: string enum: - AUTH_REQUIRED - PAYMENT_REQUIRED - RATE_LIMITED - BAD_REQUEST - FORBIDDEN - NOT_FOUND - CONFLICT - PRICE_CHANGED - QUOTE_EXPIRED - TRIP_EXPIRED - TRIP_STATE_CONFLICT - OFFER_EXPIRED - OFFER_UNAVAILABLE - MISSING_CUSTOMER_DETAILS - CURRENCY_UNSUPPORTED - 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. Codes are only ever ADDED, in a minor version, so treat an unknown one as its HTTP status. example: BAD_REQUEST message: type: string doc_url: type: string required: - code - message required: - error IntentInput: type: object properties: user_intent: type: string nullable: true description: >- The user's natural-language intent: the Alpic PII-stripped paraphrase when available, else a best-effort fallback to the client-provided NL query. example: find a cheap flight to Tokyo CarExchangeAncillarySelection: type: object properties: offer_id: type: string minLength: 1 description: >- The extra's `offer_id`, as listed on the trip item or on `current.ancillaries`. example: CHILD_SEAT quantity: type: integer minimum: 1 description: >- How many of this extra the rental should carry. Omit the line to remove it. example: 1 required: - offer_id - quantity CarExchangeRental: type: object properties: vehicle: $ref: '#/components/schemas/CarExchangeVehicle' pick_up: $ref: '#/components/schemas/CarExchangeStop' drop_off: $ref: '#/components/schemas/CarExchangeStop' ancillaries: type: array items: $ref: '#/components/schemas/CarExchangeAncillary' description: >- The rate extras the rental carries (on `current`) or would carry (on an offer), each priced by the provider for that rental. Absent when there are none. description: >- A rental: the vehicle, where it is collected and where it is returned. Used for both the booking as it stands today (`current` on the preview) and the one a candidate would replace it with (`rental` on an offer). CarAmount: type: object properties: value: type: integer description: >- Integer amount in MINOR units, always paired with decimal_places — divide by 10 ** decimal_places to display. Example: value 15977 with decimal_places 2 is 159.77 USD. Rendering this field directly shows prices 100x too high for 2-decimal currencies. example: 41250 currency: type: string description: ISO 4217 currency code. example: EUR decimal_places: type: integer description: >- Scale of the integer value/amount: display = integer / 10 ** decimal_places. Always sent alongside minor-unit amounts. Usually the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry a different scale — ALWAYS use the decimal_places sent with the amount, never a hardcoded 2. Only if the field is genuinely absent on a value-shaped object, fall back to the ISO digits for the currency. example: 2 description: The only amount Jinko charges at checkout. CarExchangeOffer: type: object properties: exchange_offer_token: type: string description: >- Opaque token of this candidate ("cxo_…"), scoped to the booking. Pass to car_exchange_commit together with the preview's exchange_id. Treat as an opaque string; the format may evolve. example: cxo_3f9a1c7e5b2d4a8c6e1f3b5d7a9c2e4f rental: $ref: '#/components/schemas/CarExchangeRental' on_request: type: boolean description: >- The supplier confirms this package after the exchange rather than instantly. price: allOf: - $ref: '#/components/schemas/CarAmount' - description: >- The candidate's full pay-now total — what the whole rental would cost, not the difference. delta: $ref: '#/components/schemas/CarExchangeDelta' required: - exchange_offer_token CarExchangeVehicle: type: object properties: name: type: string example: Peugeot 308 or similar category: type: string example: compact acriss_code: type: string example: CDMR CarExchangeStop: type: object properties: branch_name: type: string example: Lyon Saint-Exupery Airport city: type: string example: Lyon date_time: type: string description: Branch-local, no timezone. example: '2026-09-13T10:00:00' CarExchangeAncillary: type: object properties: offer_id: type: string description: >- The extra's id — the same `offer_id` the trip item's `available_ancillaries` carries. Pass it back in `ancillaries[]` on a preview to keep or add the extra. example: CHILD_SEAT label: type: string example: Child seat quantity: type: integer example: 1 paid_at: type: string enum: - now - local description: >- `now`: charged by Jinko, inside `price` and the `delta`. `local`: collected at the rental desk — shown, never part of either. price: allOf: - $ref: '#/components/schemas/CarAmount' - description: The charge at quantity one. required: - offer_id - quantity CarExchangeDelta: type: object properties: direction: type: string description: >- Which way money moves: `add_collect` — the replacement costs more and the difference is collected; `refund` — it costs less and the difference is refunded; `even` — same price. example: add_collect amount: allOf: - $ref: '#/components/schemas/CarAmount' - description: The ABSOLUTE difference. Absent when `direction` is `even`. description: >- The price difference between a candidate and what was already paid, and which way the money moves. Compared against `paid` on the preview, never against the candidate total. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key BearerAuth: type: http scheme: bearer ````