API Reference
  1. travel.tech API
  2. Bookings

Calculate pre-checkout flight costs

post
https://api.travel.tech/v1/flights/bookings/calculate-costs

Add paymentMethod for a full receipt with transaction fees.

The per-category lineItems carry the authoritative split: each item's amount is the pre-tax component, taxes the tax component, and total their sum in the same currency.

A guest-session caller may price its own locked fare here without an account. It must still send Idempotency-Key, and it must omit billingAddressId, creditCardId, creditCardOwner, invoiceProfileId, paymentMethod, and totalDiscounted — the first four and the last resolve against an account the guest session does not own, and paymentMethod would price the shared service account's own transaction-fee schedule instead of a base cost, so supplying any of them returns 422 rather than a wrongly-priced quote. isPersonal is pinned to false for a guest and any value supplied is ignored, rather than rejected, since a guest-provisioned account is never personal.

Booking-create (POST /v1/flights/bookings) books exactly the ancillaries selections priced here, but does not itself accept a guest session bearer: a guest completes the account-provisioning exchange first, then books with the resulting bearer.

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

Flights-only calculate-costs request.

Typed via :class:FlightAncillarySelectionMixin, listed first so its
ancillaries: list[FlightAncillarySelectionIn] | None field wins over
:class:CalculateCostsRequest's untyped list[dict[str, object]] | None in the MRO (neither base inherits from the other, so this is
ordinary multiple inheritance — see the mixin's docstring for why that
avoids a same-hierarchy field-override conflict). Registered under
POST /v1/flights/bookings/calculate-costs
(:mod:mercury.api.routes_flights_bookings_costs) ahead of the generic
/{vertical}/bookings/calculate-costs route so this schema — not the
untyped cross-vertical one — appears in the OpenAPI spec for flights.
Behaviour is otherwise identical: both routes share
:func:mercury.api.routes_bookings._pricing.calculate_costs_for_vertical.

string
required

Locked fare ID.

string
^[a-z]{2}_[a-z]{2}$
Defaults to en_us

Locale in ll_cc format. Defaults to en_us.

Personal booking flag. Affects license-fee and currency resolution.

enum

Payment method to price with. When omitted, the response returns base costs without payment-method transaction fees. Required to see the exact amount the user will be charged at confirm time.

[cc] Mercury card UUID from GET /v1/payment-methods. Required when paymentMethod is 'cc'.

enum

[cc] Card owner scope: user | account. Required when paymentMethod is 'cc'.

Mercury UUID of the billing address. Affects VAT resolution and currency selection. When omitted, the default from the account invoice profile is used.

Invoice profile to price with. Affects VAT resolution for corporate bookings. For stays, auto-resolved when omitted (same as booking create).

array | null

Ancillary extras (baggage, seats, lounges, etc.) to include in the price estimate. Each item: {id, quantity, passenger_id}. id must match an extra option on the fare.

array | null
deprecated

Deprecated: send all ancillary selections via ancillaries. Still accepted for back-compat; ancillaries takes precedence.

array | null

Unified ancillary selection input. Takes precedence over extraServices when both are provided. On booking-create, Mercury books exactly these selections — the same ids calculate-costs already validated resolve here as long as the fare has not expired. On calculate-costs, totalConfirmed reflects every selection priced; whether a per_passenger ancillary's contribution is already multiplied by party size is provider-computed and not independently asserted by Mercury — treat totalConfirmed as authoritative rather than re-deriving a per-passenger split from it. Use passengerCount for a client-side per-passenger display only.

array | null
deprecated

Deprecated (cars only): pay-at-desk selections now belong in the unified ancillaries field, which Mercury routes by ancillary kind. Still accepted for back-compat.

array | null

Seat selection per trip and leg for seat-map services. When present, each trip must include at least one leg and each leg at least one seat assignment. Accepts camelCase (tripId / legId / passengerId) or snake_case keys. Forwarded upstream as snake_case.

array | null

List of previously generated insurance quote IDs to include in the price.

When true, a fresh insurance quote is generated for the fare and included in the cost breakdown.

^\d+(\.\d+)?$

Discount amount to apply as a decimal string (e.g. '10.00'). Subtracted from the computed total before returning totalConfirmed. Used for wallet-balance or negotiated discounts.

≥ 1

Total traveler count for this booking (e.g. adults + children + infants for a flight, or total guests for a stay). When supplied, echoed onto every response line item's passengerCount field so a client can render a per-passenger breakdown (e.g. 'Fare cost — 2 x EUR 53.50') without Mercury asserting how the provider amount decomposes across passengers. Optional; existing callers that omit it see unchanged behaviour.

Headers

Client-generated idempotency key (UUID v4 recommended). Required on all booking mutation requests. Whether a repeated key replays the first response depends on the operation; see its description and the idempotency and retries guide.

Responses

401

Missing or invalid authentication

404

Referenced resource not found

410

Offer expired — the fare behind this quote is gone. Returned as OFFER_EXPIRED with recoveryAction: CHANGE_SELECTION: the same request can never succeed, so route the traveler back to fare selection instead of retrying.

422

Validation error or missing Idempotency-Key

503

Booking service not configured or temporarily unavailable

Updated 17 days ago

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

Updated 17 days ago

Did this page help you?