# Use case to event mapping

This is a quick reference that maps common travel and booking scenarios to the webhook `operation` and event type they trigger,
and describes what changes in the payload so you can identify it when the events are received.

See [booking lifecycle](/webhooks/booking-lifecycle/booking-lifecycle-intro) to understand the events generated during various travel booking scenarios.

## Choosing between PNR_V3 and TRIP_DETAILS_V3

The [PNR_V3](/openapi/webhookeventapi/webhooks/paths/pnr_v3/post) event provides detail at a PNR level (per booking),
while the [TRIP_DETAILS_V3](/openapi/webhookeventapi/webhooks/paths/trip_details_v3/post) event provides detail at a trip level (a collection of PNRs).
The main difference is the level (PNR vs a trip) at which the detail is provided.

Use the [PNR_V3](/openapi/webhookeventapi/webhooks/paths/pnr_v3/post) webhook for most cases.
However, for scenarios where you need to update the entire trip based on a change to a single booking,
use the [TRIP_DETAILS_V3](/openapi/webhookeventapi/webhooks/paths/trip_details_v3/post) event.
For example, if you consolidate expenses for an entire trip within a single receipt,
or you maintain a trip summary that needs to be updated whenever any booking in the trip changes, use `TRIP_DETAILS_V3`.

## Air bookings

**Event types used:** [PNR_V3](/openapi/webhookeventapi/webhooks/paths/pnr_v3/post), [TRIP_DETAILS_V3](/openapi/webhookeventapi/webhooks/paths/trip_details_v3/post), and [SERVICE_CHARGE](/openapi/webhookeventapi/webhooks/paths/service_charge/post)

All operations, except where noted, apply to both the [TRIP_DETAILS_V3](/openapi/webhookeventapi/webhooks/paths/trip_details_v3/post) and [PNR_V3](/openapi/webhookeventapi/webhooks/paths/pnr_v3/post) event types.

| Use case  | Operation  | Payload changes |
|  --- | --- | --- |
| Air booking created | `BOOKING_CREATED` | The PNR's `bookingStatus` changes to `CONFIRMED_STATUS`.
**Notes:*** When an approval is required, the `bookingStatus` may show the `PENDING_STATUS` or `APPROVAL_REQUESTED_STATUS` value. At this point, the reservation may have already been accepted by the supplier, but the ticket is not issued until the approval completes.
* After the [approval](/spotnana/basic_approval_concepts), the `bookingStatus` changes to `CONFIRMED_STATUS` and a `BOOKING_TICKETED` operation is executed.
* For bookings that use pre-approval, the booking itself is created only after the approver approves the request.

 |
| Payment failed or declined | `PAYMENT_DECLINED` | The PNR's `bookingStatus` changes to `PAYMENT_DECLINED_STATUS` indicating a payment failure. Manual intervention might be required to retry the booking creation. |
| Air ticket issued | `BOOKING_TICKETED` | A new entry is added to the `airPnr` > `travelerInfos` > `tickets` array with the `ISSUED` status.
The webhook's `operationSummary` > `ticketsIssued` field lists the new ticket numbers. |
| Multi-traveler PNR split into separate PNRs | `SPLIT_PNR_CREATED` | Each child PNR created from the split is delivered as separate [PNR_V3](/openapi/webhookeventapi/webhooks/paths/pnr_v3/post) events with this operation. |
| Booking canceled within the void window | `TICKET_VOIDED` | An air ticket with `airPnr` > `travelerInfos` > `tickets` > `status` changes from `ISSUED` to `VOIDED`.
For a full void, the PNR's `bookingStatus` changes to `CANCELLED_STATUS`.
The webhook's `operationSummary` > `ticketsVoided` field lists the voided tickets. |
| Booking canceled after the void period (refund) | `TICKET_REFUNDED` | An air ticket with `airPnr` > `travelerInfos` > `tickets` > `status` changes from `ISSUED` to `REFUNDED`.
The webhook's `operationSummary` > `ticketsRefunded` field lists the refunded tickets. |
| Ticket exchanged (new ticket issued) | `BOOKING_TICKETED` and `TICKET_REFUNDED` | The original ticket's status in the `airPnr` > `travelerInfos` > `tickets` array changes from `ISSUED` to `EXCHANGED`,
and a new ticket is added with the `ISSUED` status and its `exchangeInfo` field is updated with the exchange information. |
| Flight changed without a new ticket (revalidation) | `FLIGHT_CHANGED` | The flight details in the `airPnr` > `legs` > `flights` array change while the original ticket remains in the `ISSUED` status. |
| Airline announces a schedule change | `FLIGHT_SCHEDULE_CHANGE_PENDING` | The `airPnr` > `legs` > `flights` > `flightStatus` changes from `CONFIRMED` to `SCHEDULE_CHANGE`. |
| Schedule change confirmed or canceled | `FLIGHT_SCHEDULE_CHANGE_CLOSED` | The `airPnr` > `legs` > `flights` > `flightStatus` changes from `SCHEDULE_CHANGE` to `CONFIRMED`.
If the traveler was waitlisted while accepting the change, the `flightStatus` can instead show the `SCHEDULE_CHANGE_WAITLISTED_BOOKING` value, which requires agent follow-up. |
| Cabin upgraded or downgraded | `FLIGHT_CABIN_CHANGED` | The `airPnr` > `legs` > `flights` > `cabin` differs from the previous PNR version. |
| Seat reservation confirmed | `FLIGHT_SEAT_CONFIRMED` | The `airPnr` > `travelerInfos` > `booking` > `seats` > `status` changes to `CONFIRMED`. |
| Seat reservation canceled by the airline | `FLIGHT_SEAT_CANCELLED` | The `airPnr` > `travelerInfos` > `booking` > `seats` > `status` changes from `CONFIRMED` or `PENDING` to `CANCELLED`. |
| Seat number changed by the airline | `FLIGHT_SEAT_CHANGED` | The `airPnr` > `travelerInfos` > `booking` > `seats` > `number` changes while the seat `status` remains `CONFIRMED`. |
| Flight segment canceled | `FLIGHT_CANCELLED` | The `airPnr` > `legs` > `flights` > `flightStatus` changes to `CANCELLED`. |
| Trip information modified | `TRIP_UPDATED` | The trip information (e.g., the trip name or description) changes. The booking itself is unchanged. |
| Miscellaneous PNR update | `BOOKING_OTHER_UPDATE` | The PNR version increments without a category-specific change (e.g., a remark added on the PNR). This is a catchall operation for any miscellaneous PNR or trip updates. |
| Invoice created | `INVOICE_GENERATED` | A new entry is added to the `invoiceInfos` array. The `operationSummary` > `invoiceGeneratedDocIds` field lists the document IDs of the invoices issued as part of this event, which you can use with the [get document](/openapi/documentapi/documents/getdocument) API to download the invoice.
This operation is delivered on `PNR_V3` subscriptions only. |
| TMC service fee charged | `SERVICE_FEE` | The fee details are delivered on the `SERVICE_CHARGE` event with operation type `SERVICE_FEE`.
On PNR payloads, the fees are listed under the `serviceFees` array. |


There is no operation for a successful payment.
A successful air payment is implicit in the `BOOKING_TICKETED` operation, which represents ticket issuance.

## Hotel bookings

**Event types used:** [PNR_V3](/openapi/webhookeventapi/webhooks/paths/pnr_v3/post), [TRIP_DETAILS_V3](/openapi/webhookeventapi/webhooks/paths/trip_details_v3/post), and [SERVICE_CHARGE](/openapi/webhookeventapi/webhooks/paths/service_charge/post)

All operations, except where noted, apply to both the [TRIP_DETAILS_V3](/openapi/webhookeventapi/webhooks/paths/trip_details_v3/post) and [PNR_V3](/openapi/webhookeventapi/webhooks/paths/pnr_v3/post) event types.

| Use case  | Operation  | Payload changes |
|  --- | --- | --- |
| Hotel booking created | `BOOKING_CREATED` | The `hotelPnr` > `pnrStatus` changes to `CONFIRMED`, and the PNR's `bookingStatus` changes to `CONFIRMED_STATUS`. |
| Dates, room type, or rate changed on the same booking | `BOOKING_UPDATED` | The same PNR is delivered with the updated dates, room, or pricing details. |
| Rebooked with a different confirmation number | `BOOKING_REBOOKED` | The `hotelPnr` > `vendorConfirmationNumber` changes while the `pnrStatus` remains `CONFIRMED`.
Compare the confirmation number with the previous PNR version to detect the rebooking. |
| Canceled and rebooked as a new PNR | `BOOKING_CANCELED_BY_TRAVELER`, then `BOOKING_CREATED` | The original PNR is canceled and a new PNR is created that references it. |
| Booking canceled by the traveler | `BOOKING_CANCELED_BY_TRAVELER` | The `hotelPnr` > `pnrStatus` changes from `CONFIRMED` to `CANCELLED` or `VOIDED`,
and the PNR's `bookingStatus` changes to `CANCELLED_STATUS`. |
| Booking canceled by the property or vendor | `BOOKING_CANCELED_BY_VENDOR` | The `hotelPnr` > `pnrStatus` changes from `CONFIRMED` to `CANCELLED` or `VOIDED`,
and the PNR's `bookingStatus` changes to `CANCELLED_STATUS`. |
| Booking metadata updated (e.g., updating loyalty number, special requests, etc) | `BOOKING_UPDATED` or `BOOKING_OTHER_UPDATE` | The PNR is delivered with the updated metadata. The statuses are unchanged. |
| Invoice created | `INVOICE_GENERATED` | A new entry is added to the `invoiceInfos` array. The `operationSummary` > `invoiceGeneratedDocIds` field lists the document IDs of the invoices issued as part of this event, which you can use with the [get document](/openapi/documentapi/documents/getdocument) API to download the invoice.
This operation is delivered on `PNR_V3` subscriptions only. |
| TMC service fee charged | `SERVICE_FEE` | The fee details are delivered on the `SERVICE_CHARGE` event with operation type `SERVICE_FEE`.
On PNR payloads, the fees are listed under the `serviceFees` array. |


## Car rentals

**Event types used:** [PNR_V3](/openapi/webhookeventapi/webhooks/paths/pnr_v3/post), [TRIP_DETAILS_V3](/openapi/webhookeventapi/webhooks/paths/trip_details_v3/post), and [SERVICE_CHARGE](/openapi/webhookeventapi/webhooks/paths/service_charge/post)

All operations, except where noted, apply to both the [TRIP_DETAILS_V3](/openapi/webhookeventapi/webhooks/paths/trip_details_v3/post) and [PNR_V3](/openapi/webhookeventapi/webhooks/paths/pnr_v3/post) event types.

| Use case  | Operation  | Payload changes |
|  --- | --- | --- |
| Rental car booking made | `BOOKING_CREATED` | The `carPnr` > `pnrStatus` changes to `CONFIRMED`, and the PNR's `bookingStatus` changes to `CONFIRMED_STATUS`. |
| Pickup or drop-off date, time, or location changed | `BOOKING_UPDATED` | The same PNR is delivered with the updated pickup or drop-off details. |
| Vehicle type changed | `BOOKING_UPDATED` or `BOOKING_REBOOKED` | If the vehicle details (i.e., class, make, or model) are changed, the event is delivered with operation type `BOOKING_UPDATED`.
If the supplier issues a new vendor confirmation number for the change, the `BOOKING_REBOOKED` operation is also triggered. |
| Rebooked with a different confirmation number | `BOOKING_REBOOKED` | The `carPnr` > `vendorConfirmationNumber` changes while the `pnrStatus` remains `CONFIRMED`. |
| Booking canceled by the traveler | `BOOKING_CANCELED_BY_TRAVELER` | The `carPnr` > `pnrStatus` changes from `CONFIRMED` to `CANCELLED` or `VOIDED`,
and the PNR's `bookingStatus` changes to `CANCELLED_STATUS`. |
| Booking canceled by the vendor | `BOOKING_CANCELED_BY_VENDOR` | The `carPnr` > `pnrStatus` changes from `CONFIRMED` to `CANCELLED` or `VOIDED`,
and the PNR's `bookingStatus` changes to `CANCELLED_STATUS`. |
| Metadata updated (loyalty number) | `BOOKING_UPDATED` or `BOOKING_OTHER_UPDATE` | The PNR is delivered with the updated metadata. The statuses are unchanged. |
| Invoice created | `INVOICE_GENERATED` | A new entry is added to the `invoiceInfos` array. The `operationSummary` > `invoiceGeneratedDocIds` field lists the document IDs of the invoices issued as part of this event, which you can use with the [get document](/openapi/documentapi/documents/getdocument) API to download the invoice.
This operation is delivered on `PNR_V3` subscriptions only. |
| TMC service fee charged | `SERVICE_FEE` | The fee details are delivered on the `SERVICE_CHARGE` event.
On PNR payloads, the fees are listed under the `serviceFees` array. |


## Rail bookings

**Event types used:** [PNR_V3](/openapi/webhookeventapi/webhooks/paths/pnr_v3/post), [TRIP_DETAILS_V3](/openapi/webhookeventapi/webhooks/paths/trip_details_v3/post), and [SERVICE_CHARGE](/openapi/webhookeventapi/webhooks/paths/service_charge/post)

All operations, except where noted, apply to both the [TRIP_DETAILS_V3](/openapi/webhookeventapi/webhooks/paths/trip_details_v3/post) and [PNR_V3](/openapi/webhookeventapi/webhooks/paths/pnr_v3/post) event types.

> **Note:** A rail PNR may contain an outward journey and a return journey, and each journey can be made up of multiple sections (e.g., sold by different rail vendors).
Inspect the `railPnr` > `outwardJourney` > `journeyStatus` and `railPnr` > `inwardJourney` > `journeyStatus`
for the journey status, and the `railPnr` > `sections` > `sectionStatus` for section-level statuses.


| Use case  | Operation  | Payload changes |
|  --- | --- | --- |
| Rail booking made | `BOOKING_CREATED` | The journey and section statuses show `CONFIRMED`, and the PNR's `bookingStatus` changes to `CONFIRMED_STATUS`. |
| Booking exchanged (passenger details, travel card, new booking number, or journey changes) | `EXCHANGE` | The PNR is delivered with the updated journey details and its `railPnr` > `exchangeInfo` populated. |
| Seat preference changed | `BOOKING_UPDATED` | The PNR is delivered with the updated seat preferences. |
| Booking canceled | `REFUND` | The following statuses are changed in the payload:* The `railPnr` > `outwardJourney` > `journeyStatus` changes from `CONFIRMED` to `CANCELLED`,
* The `railPnr` > `sections` > `sectionStatus` changes to `CANCELLED`,
* The PNR's `bookingStatus` changes to `CANCELLED_STATUS`.

 |
| Booking partially canceled (some sections not canceled) | `REFUND` | The `railPnr` > `sections` > `sectionStatus` of the canceled sections changes to `CANCELLED` while the remaining sections may remain as `CONFIRMED`. |
| Metadata updated (e.g., updating special requests) | `BOOKING_UPDATED` or `BOOKING_OTHER_UPDATE` | The PNR is delivered with the updated metadata. The statuses remain unchanged. |
| Invoice created | `INVOICE_GENERATED` | A new entry is added to the `invoiceInfos` array. The `operationSummary` > `invoiceGeneratedDocIds` field lists the document IDs of the invoices issued as part of this event, which you can use with the [get document](/openapi/documentapi/documents/getdocument) API to download the invoice.
This operation is delivered on the `PNR_V3` subscriptions only. |
| Cancellation fee charged | `SERVICE_FEE` | The fee is delivered on the `SERVICE_CHARGE` event with the `charge` > `feeInfo` > `transactionFeeType` set to `TRANSACTION_TYPE_CANCELLATION`. |


## Approvals

**Event type used:** [PNR_APPROVAL](/openapi/webhookeventapi/webhooks/paths/pnr_approval/post) and [PNR_V3](/openapi/webhookeventapi/webhooks/paths/pnr_v3/post).

The [PNR_APPROVAL](/openapi/webhookeventapi/webhooks/paths/pnr_approval/post) event notifies you when a booking's approval state changes.
The corresponding PNR also carries the approval state in the `approvalInfo` > `approvalStatus` field
on [PNR_V3](/openapi/webhookeventapi/webhooks/paths/pnr_v3/post) payloads.

| Use case  | Operation  | Payload changes |
|  --- | --- | --- |
| Approval requested and awaiting approver action | `APPROVAL_PENDING` | The `approvalInfo` > `approvalStatus` changes to `APPROVAL_PENDING`.
The PNR's `bookingStatus` shows `APPROVAL_REQUESTED_STATUS`. |
| Approver has approved the booking | `APPROVED` | The `approvalInfo` > `approvalStatus` changes to `APPROVED`,
and the PNR's `bookingStatus` moves to `CONFIRMED_STATUS`. |
| Approver has denied the booking | `DENIED` | The `approvalInfo` > `approvalStatus` changes to `DENIED`,
and the PNR's `bookingStatus` moves to `APPROVAL_DENIED_STATUS`.
For a ticketed air booking, a `TICKET_VOIDED` operation follows on the `PNR_V3` event as the booking is voided. |
| Hard-approval deadline passed without a response | `TIMED_OUT` | The itinerary is canceled because no approver took action before the approval deadline. |
| Reminder sent before the approval deadline | `TIMED_OUT_REMINDER` | A reminder notification is sent to the approver. The approval status remains unchanged. |


## Service charges

**Event type used:** [SERVICE_CHARGE](/openapi/webhookeventapi/webhooks/paths/service_charge/post)

Service charge events are delivered with `operation` as `SERVICE_FEE`.
In the event payload, the `serviceType` identifies whether the fee relates to an itinerary transaction (`ITINERARY_BOOKING`)
or an agent contact (`AGENT_CONTACT`),
and the `charge` > `feeInfo` > `transactionFeeType` identifies why the fee was charged.
The event is triggered even if the fee amount is 0.

| Use case  | `transactionFeeType` value  | Payload changes |
|  --- | --- | --- |
| Fee for a new booking (air, hotel, car, rail, or limo) | `TRANSACTION_TYPE_BOOKING` | The fee amount and breakdown are delivered in the `charge` object. |
| Fee for modifying or exchanging an existing booking | `TRANSACTION_TYPE_MODIFICATION` | The modification fee details are delivered in the `charge` object. |
| Fee for canceling an existing booking | `TRANSACTION_TYPE_CANCELLATION` | The cancellation fee details are delivered in the `charge` object. |
| Fee for an agent-assisted transaction | `TRANSACTION_TYPE_AGENT_CONTACT` | The `agentContact` > `contactOp` identifies the agent operation
(e.g., `ANCILLARY_PURCHASE`, or a `SHELL_PNR_CREATE`, etc.),
and the `agentContact` > `contactType` identifies the contact method (`PHONE`, `CHAT`, or `EMAIL`). |


The service charge payload also includes a `paymentStatus`
(`SUCCESS`, `DELAYED_INVOICE`, `MANUAL`, `NO_CHARGE`, or `WAIVED_OFF`).
On `PNR_V3` payloads, the fees charged for a booking are listed under the `serviceFees` array,
where each entry has its own `status` (e.g., `ISSUED`, `VOIDED`, `NO_CHARGE`, or `WAIVED_OFF`).

## Traveler profiles and agent tasks

**Event types used:** [TRAVELER_V2](/openapi/webhookeventapi/webhooks/paths/traveler_v2/post), [AGENT_TASK_DETAILS](/openapi/webhookeventapi/webhooks/paths/agent_task_details/post)

| Use case  | Operation  | Event type |
|  --- | --- | --- |
| Traveler profile created | `CREATE` | `TRAVELER_V2` |
| Traveler profile updated | `UPDATE` | `TRAVELER_V2` |
| Traveler profile deleted | `DELETE` | `TRAVELER_V2` |
| Agent task created for a booking that needs attention | `TASK_CREATE` | `AGENT_TASK_DETAILS` |