Calculate pre-checkout costs

post

https://example.com/v1/{vertical}/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.

Guest session tokens are accepted on this operation for flights only. Every other vertical requires a traveler bearer token.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

vertical

string

enum

required

Allowed:

Body Params

Request body for POST /v1/{vertical}/bookings/calculate-costs.

fareId

string

required

Locked fare ID.

locale

string

^[a-z]{2}_[a-z]{2}$

Defaults to en_us

Locale in ll_cc format. Defaults to en_us.

isPersonal

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

paymentMethod

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.

creditCardId

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

creditCardOwner

enum

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

billingAddressId

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

invoiceProfileId

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

flightExtras

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.

extraServices

array | null

deprecated

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

ancillaries

array | null

Unified ancillary selection input. Each item: {id, quantity, passenger_id}. Takes precedence over extraServices when both are provided. For cars, both booking-flow and pay-at-desk selections go here; Mercury routes each to the correct provider bucket by its ancillary kind, so requestServices is no longer needed.

requestServices

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.

seats

array | null

Seat selection per trip and leg for seat-map services. Only meaningful when extraServices includes seat-type entries. Shape: [{trip_id, legs: [{leg_id, seats: [{seat, passenger_id}]}]}].

insuranceQuotes

array | null

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

requestInsuranceQuote

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

totalDiscounted

^\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.

passengerCount

≥ 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

Idempotency-Key

Client-generated idempotency key (UUID v4 recommended). Required on all booking mutation requests to prevent duplicate bookings on retry.

Responses

401

Missing or invalid authentication

404

Referenced resource not found

410

Offer expired — the fare behind this quote is gone, on any vertical. 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

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Successful Response