---
title: "Change an offer's amount"
method: PATCH
path: "/api/v1/offers/{offerReference}"
tags: ["Execute"]
---

# Change an offer's amount

`PATCH /api/v1/offers/{offerReference}`

## Request

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

The MCP `modify_bid` tool. Each change counts toward the per-booking cap (3 by default); once reached the answer is 409 with code REASON_CHANGE_LIMIT and the current offer stands.

## Path parameters

- `offerReference` string, required

## Request body

- ModifyOfferRequest
  - `quoteId` string, required
  - `amount` number, required: The NEW amount in the offer currency.
  - `quantity` integer
  - `confirm` boolean: Human-in-the-loop confirm (see OfferRequest.confirm).
  - `conversationId` string

## Response `200`

Offer updated (or re-staged for payment).

- union
  - Offer
    - `quoteId` string, required
    - `offerReference` string, nullable, required: Operator order-change id when one exists, else the option's offerId.
    - `offerReferences` string[], required: All operator order-change ids created/affected by this call.
    - `offerId` string, nullable, required
    - `stage` 'needs_payment' | 'needs_confirmation' | 'submitted' | 'rejected' | 'unavailable', required
    - `status` 'pending_confirmation' | 'pending_payment' | 'submitted' | 'rejected' | 'unavailable', required
    - `ok` boolean, required
    - `purchaseType` 'BID' | 'INSTANT' | 'POINTS', required
    - `cabin` string, nullable, required
    - `segment` Segment, required
      - `origin` string, required: IATA airport/port code.
      - `destination` string, required
      - `flightNumber` string, required
      - `departureDate` string, nullable, required: ISO date.
    - `amount` number, nullable, required
    - `currency` string, nullable, required: ISO currency, or PTS for a points amount.
    - `quantity` integer, required
    - `paymentUrl` string, nullable, required: The operator's hosted payment / confirmation page (pay-by-link). Card details are captured there, never by this API.
    - `message` string, required: Human-readable next step, safe to relay to the traveler.
    - `reason` string, nullable, required: Rejection token on failures.
    - `changesRemaining` integer, required
  - ModifiedOffer
    - `quoteId` string, required
    - `offerReference` string, required
    - `offerReferences` string[], required
    - `stage` 'updated', required
    - `status` 'submitted', required
    - `ok` boolean, required
    - `amount` number, required
    - `currency` string, nullable, required
    - `paymentUrl` string, nullable, required
    - `message` string, required
    - `changesRemaining` integer, required

## Other responses

- `202`: Awaiting human confirmation — repeat with confirm: true.
- `400`: amount missing or invalid.
- `401`: Missing, invalid, expired, or revoked bearer token. The WWW-Authenticate challenge points at the OAuth protected-resource metadata.
- `404`: Unknown quote/offer, or owned by another caller.
- `409`: Change limit reached (REASON_CHANGE_LIMIT), quote not ready, or not eligible.
- `422`: Amount outside the operator's range.
- `429`: Per-caller rate limit exceeded.
- `503`: Operator update failed — retry.

---

[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)