> ## Documentation Index
> Fetch the complete documentation index at: https://docs.travomatrix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Booking Status & Lifecycle

Monitoring the state of a booking is critical for accurate order management. Travomatrix uses a formal state machine to govern the lifecycle of every flight reservation.

## Booking State Machine

Every booking transition is validated against a strict state machine to prevent invalid operations (like issuing a ticket for a cancelled booking).

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING: booking/create
    PENDING --> BOOKED: PNR Created
    PENDING --> FAILED: Error
    BOOKED --> TICKETED: booking/ticket
    BOOKED --> CANCELLED: Void/Voided
    BOOKED --> FAILED: issuance_error
    TICKETED --> RESCHEDULED: booking/reschedule
    TICKETED --> PARTIALLY_CANCELLED: booking/partial-cancel
    TICKETED --> CANCELLED: booking/cancel
    TICKETED --> FLOWN: Segment Flown
    RESCHEDULED --> FLOWN
    PARTIALLY_CANCELLED --> FLOWN
    PARTIALLY_CANCELLED --> CANCELLED
    CANCELLED --> REFUNDED: wallet/credit
```

## Status Values

| Status      | Description                                                                  |
| ----------- | ---------------------------------------------------------------------------- |
| `PENDING`   | The booking request is being processed by the provider.                      |
| `BOOKED`    | The PNR has been generated but not yet ticketed.                             |
| `TICKETED`  | The ticket numbers have been issued. The passenger is ready to fly.          |
| `FAILED`    | The booking or ticketing attempt failed permanently.                         |
| `CANCELLED` | The booking has been voided or cancelled by the user or administrator.       |
| `REFUNDED`  | The refund amount has been successfully credited back to the agent's wallet. |
| `FLOWN`     | All segments in the booking have been completed.                             |

## Polling vs. Events

While you can poll this endpoint using the `booking_id` or `pnr`, we recommend using the **X-Request-ID** for tracking asynchronous operations. For production integrations, consider setting up a Webhook listener (Enterprise only).


## OpenAPI

````yaml POST /flight/booking/status
openapi: 3.0.3
info:
  title: Travomatrix B2B Travel API
  version: 1.0.0
  description: >
    Travomatrix is a high-performance multi-vertical travel booking engine
    designed for B2B enterprises.


    ### Verticals Supported

    - **Flights**: Unified interface for global GDS and NDC providers.

    - **Hotels**: Coming Soon.

    - **Rail**: Coming Soon.

    - **Cabs**: Coming Soon.


    ### Key Security & Reliability Headers

    - **X-API-Key**: Your primary server-to-server API key.

    - **Idempotency-Key**: Required for financial operations. Prevents duplicate
    actions on retries.

    - **X-Request-ID**: Optional but recommended. Used for tracing requests
    through the Travomatrix infrastructure.
servers:
  - url: https://api.travomatrix.com/api/v1
    description: Production Environment
  - url: http://uat.travomatrix.com/api/v1
    description: UAT Environment
  - url: http://localhost:80/api/v1
    description: Localhost (Port 80)
  - url: http://localhost:8080/api/v1
    description: Localhost (Port 8080)
security: []
paths:
  /flight/booking/status:
    post:
      tags:
        - Flights - Booking
      summary: Get Booking Details
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                booking_id:
                  type: string
                pnr:
                  type: string
      responses:
        '200':
          description: Current booking state and PNR details.
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````