Refunds, changes & schedule changes

After ticketing, changes go through servicing requests: you ask, our ticketing desk gets the airline's conditions and sends you a quote, you accept or decline. Nothing is charged or refunded until you accept.

Request types

Flow

requested ──► in_review ──► quoted ──accept──► accepted ──► executing ──► completed
                 │             ├──decline──► declined
                 │             └──(expires)─► quote_expired
                 └──► rejected (the desk/airline refused; see history)
(any time before accepting) ──withdraw──► withdrawn
executing ──► failed (rare; the desk follows up)

1. Create a request

curl -X POST $TAM_URL/flights/bookings/7c1e.../post-booking-requests \
  -H "Authorization: Bearer $TAM_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "type": "refund", "passengerIndexes": [0], "note": "Customer cancelled" }'

• passengerIndexes / sliceIndexes — from passengers[].index and the slice order; empty means all.
• One open request per booking at a time (flights.servicing_request_open).
• Scope: flights:post_booking.

2. Receive the quote

Wait for the flight.post_booking_request.updated webhook (or poll GET …/post-booking-requests/{requestId}). When status is quoted:

{
  "id": "5e2d…", "requestNumber": "PBR-…", "type": "refund", "status": "quoted",
  "quote": {
    "airlinePenalty": { "amount": "18.00", "currency": "USD" },
    "serviceFee":     { "amount": "0.00",  "currency": "USD" },
    "fareDifference": { "amount": "0.00",  "currency": "USD" },
    "refundAmount":   { "amount": "162.00", "currency": "USD" },
    "collectAmount":  { "amount": "0.00",  "currency": "USD" },
    "expiresAt": "2026-11-21T10:00:00Z"
  },
  "nextActions": [
    { "action": "accept_quote",  "method": "POST", "href": "/flights/bookings/7c1e…/post-booking-requests/5e2d…/accept",  "deadline": "2026-11-21T10:00:00Z" },
    { "action": "decline_quote", "method": "POST", "href": "/flights/bookings/7c1e…/post-booking-requests/5e2d…/decline", "deadline": "2026-11-21T10:00:00Z" },
    { "action": "withdraw", … }
  ]
}

• refundAmount is credited to your wallet, collectAmount is charged to it, when you accept.
• The booking shows pendingReason: awaiting_quote_decision meanwhile.

3. Accept or decline

curl -X POST $TAM_URL/flights/bookings/7c1e.../post-booking-requests/5e2d.../accept \
  -H "Authorization: Bearer $TAM_KEY" -H "Idempotency-Key: $(uuidgen)"

After acceptance the desk executes the change with the airline. On completed, outcome shows what was refunded or collected, and for a change the newPnr / newBookingId. The booking updates accordingly: a full refund makes it cancelled; a partial one marks the passengers cancelled in passengers[].state.

Decline with POST …/decline (optional { "note": "…" }); withdraw a request you no longer need with POST …/withdraw.

Schedule changes

Airlines change flight times, numbers or routings after ticketing. When that happens:

1. You receive flight.booking.schedule_changed, and the booking lists the notice in openScheduleChanges.
2. GET /flights/bookings/{id}/schedule-changes shows the original and the new segments, requiresAcceptance and replyDeadline.
3. Then:
   • No acceptance needed (information only): POST …/schedule-changes/{id}/acknowledge.
   • Acceptance needed: inform the passenger, then POST …/schedule-changes/{id}/accept before replyDeadline. The booking shows pendingReason: awaiting_schedule_change_reply until then.
   • Passenger refuses the new schedule: do not accept; create a refund or change_date request instead — an involuntary change usually waives penalties.

Errors you may see