---
title: "Quote: live eligibility check for a booking"
method: POST
path: "/api/v1/quotes"
tags: ["Quote"]
---

# Quote: live eligibility check for a booking

`POST /api/v1/quotes`

## Request

- Base URL: `https://www.upgradeagent.ai`
- URL: `https://www.upgradeagent.ai/api/v1/quotes`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://www.upgradeagent.ai/api/oauth/authorize`, token URL `https://www.upgradeagent.ai/api/oauth/token`, scopes: `mcp`)
  - HTTP bearer

Runs the same path as the MCP `check_upgrade_eligibility` tool and stores a quote owned by the caller when the booking is transactable (ELIGIBLE or MODIFY). The booking reference and last name are used only for the upstream lookup — never stored, logged, or echoed. Agents that must not handle PII should use `/api/v1/quotes/secure`.

## Request body

- QuoteRequest
  - `bookingReference` string, required: Booking reference / PNR. Used only for the upstream lookup — never stored, logged, or echoed.
  - `lastName` string, required: Passenger last name exactly as on the booking. Never stored, logged, or echoed.
  - `carrier` string, required: Operator IATA code or name, e.g. 'LX' or 'SWISS'.
  - `language` string: ISO 639-1 language for the operator's offer page (default en).
  - `conversationId` string: Optional stable id for trace correlation across quote → offer → confirm.

## Response `200`

Checked, but nothing to transact (NOT_ELIGIBLE, PNR_NOT_FOUND, NOT_CONFIGURED, or ERROR); quoteId is null.

- Quote
  - `quoteId` string, nullable, required: Null when the booking isn't transactable (no quote is stored).
  - `status` 'ELIGIBLE' | 'MODIFY' | 'NOT_ELIGIBLE' | 'PNR_NOT_FOUND' | 'NOT_CONFIGURED' | 'ERROR', required
  - `carrier` string, nullable, required: Carrier as supplied by the caller.
  - `carrierCode` string, nullable, required: Operating carrier IATA code from the booking.
  - `options` QuoteOption[], required
    - `offerId` string, required: Deterministic, non-PII id for this cabin+segment — pass as offerReference to PATCH/DELETE/price.
    - `cabin` string, required: Target cabin: BUSINESS | FIRST | PREMIUM_ECONOMY | …
    - `productName` string, required
    - `segment` Segment, required
      - `origin` string, required: IATA airport/port code.
      - `destination` string, required
      - `flightNumber` string, required
      - `departureDate` string, nullable, required: ISO date.
    - `bid` BidRange, required: The operator's live bid range for this option. Offers outside it are rejected.
      - `currency` string, required
      - `minimum` number, nullable, required
      - `suggested` number, nullable, required
      - `maximum` number, nullable, required
    - `instant` object, nullable, required
      - `currency` string, required
      - `price` number, required: The operator's fixed buy-now price.
    - `points` object, nullable, required
      - `minimum` number, nullable, required
      - `suggested` number, nullable, required
      - `maximum` number, nullable, required
    - `existingOffer` object, nullable, required: An offer already on the booking for this option at quote time.
      - `amount` number, nullable, required
      - `currency` string, nullable, required
      - `status` string, required
  - `operatorUrl` string, nullable, required: The operator's hosted upgrade page for this booking (pay-by-link target).
  - `changesRemaining` integer, required: Offer changes still allowed on this booking through the API.
  - `changesLimit` integer, required
  - `expiresAt` string, nullable, required: ISO timestamp — when the quote stops being readable/executable.
  - `message` string, nullable, required

## Other responses

- `201`: Transactable quote (status ELIGIBLE or MODIFY) with a quoteId.
- `400`: Missing bookingReference, lastName, or carrier.
- `401`: Missing, invalid, expired, or revoked bearer token. The WWW-Authenticate challenge points at the OAuth protected-resource metadata.
- `429`: Per-caller rate limit exceeded.

---

[API](https://skmtc.dev/upgradeagent/apis/upgrade-agent-rest-api.md) · [All operations](https://skmtc.dev/upgradeagent/apis/upgrade-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/upgradeagent/apis/upgrade-agent-rest-api/revisions/fbed715712c1?raw)