Execute

Execute: place a bid, buy an instant upgrade, or redeem points

The MCP place_bid tool. Validates the amount against the operator's live range and stages the offer; payment completes on the operator's hosted page (paymentUrl). When live submit is enabled, the first call without confirm: true returns 202 with stage needs_confirmation and submits nothing.

post/api/v1/offers

Request

  • Base URL: https://www.upgradeagent.ai
  • URL: https://www.upgradeagent.ai/api/v1/offers
  • 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

Request body

quoteIdstring required
purchaseType'BID' | 'INSTANT' | 'POINTS'

BID (money offer, default), INSTANT (buy now at the operator's fixed price — omit amount), or POINTS (amount = points).

amountnumber

Offer amount in the option's currency (or points). Omit for INSTANT.

cabin'BUSINESS' | 'FIRST' | 'PREMIUM_ECONOMY'

Target cabin when the quote has more than one option.

segmentstring

Route 'YUL-LHR' or flight number when more than one segment is eligible.

quantityinteger

Seats (default 1).

confirmboolean

Human-in-the-loop: set true to commit once the traveler has confirmed. When live submit is enabled, a first call without it returns 202 + stage needs_confirmation.

conversationIdstring

Response

Offer staged or submitted; complete payment at paymentUrl when present.

quoteIdstring required
offerReferencestring nullable required

Operator order-change id when one exists, else the option's offerId.

offerReferencesstring[] required

All operator order-change ids created/affected by this call.

offerIdstring nullable required
stage'needs_payment' | 'needs_confirmation' | 'submitted' | 'rejected' | 'unavailable' required
status'pending_confirmation' | 'pending_payment' | 'submitted' | 'rejected' | 'unavailable' required
okboolean required
purchaseType'BID' | 'INSTANT' | 'POINTS' required
cabinstring nullable required
amountnumber nullable required
currencystring nullable required

ISO currency, or PTS for a points amount.

quantityinteger required
paymentUrlstring nullable required

The operator's hosted payment / confirmation page (pay-by-link). Card details are captured there, never by this API.

messagestring required

Human-readable next step, safe to relay to the traveler.

reasonstring nullable required

Rejection token on failures.

changesRemaininginteger required

Changes

No recorded changes to this operation across all 1 revision of this API.