Changelog

2026-09-02

Added Change Passenger Info examples and reorganized Modify booking navigation

• Added Change Passenger Info request and response examples using modification type 40.
• Reorganized Modify booking navigation into action-oriented sub-items.

2026-09-01

Added passenger and segment cancellation

• Updated document about cancelling passenger (modification type 2) and cancelling segment (modification type 10) for AirBookModifyRQ.

2026-07-31

Add penalty rules for OTA_AirBookRS, OTA_AirPriceRS

• Penalty rules are returned under:
  • voluntaryRefunds.TPA_Extensions.penaltyRules: Provides the charges and penalties applicable to voluntary refunds or cancellations. (See more details, Retrieve Booking)
  • voluntaryChanges.TPA_Extensions.penaltyRules: Provides information about charges and penalties applicable to voluntary ticket changes. The current system returns this information for reference only; voluntary changes are not currently supported.

            "ruleInfo": {
                "chargesRules": {
                    "voluntaryRefunds": {
                        "TPA_Extensions": {
                            "penaltyRules": [
                                {
                                    "passengerTypeCode": "ADT",
                                    "rules": [
                                        {
                                            "currency": "SAR",
                                            "refundable": true,
                                            "base": 50.00,
                                            "tax": 7.50,
                                            "total": 57.50,
                                            "vat": 15.00,
                                            "applyFromTime": "2026-07-09T04:40:00Z",
                                            "applyUntilTime": "2026-07-09T05:00:00Z",
                                            "description": [
                                                {
                                                  "locale": "en_GB",
                                                  "value": "Less than 20 minutes (%)"
                                                },
                                                {
                                                  "locale": "ar_SA",
                                                  "value": "Less than 20 minutes (%)"
                                                }
                                            ]
                                          }
                                    ]
                                }
                            ]
                        }
                    },
                    "voluntaryChanges": {
                        "TPA_Extensions": {
                            "penaltyRules": [
                                {
                                    "passengerTypeCode": "ADT",
                                    "rules": [
                                        {
                                            "currency": "SAR",
                                            "refundable": true,
                                            "base": 15.00,
                                            "tax": 2.25,
                                            "total": 17.25,
                                            "vat": 15.00,
                                            "applyFromTime": "2026-07-08T05:00:00Z",
                                            "applyUntilTime": "2026-07-09T04:40:00Z",
                                            "description": [
                                                {
                                                  "locale": "en_GB",
                                                  "value": "Between 20 minutes - 24hours (%)"
                                                },
                                                {
                                                  "locale": "ar_SA",
                                                  "value": "Between 20 minutes - 24hours (%)"
                                                }
                                            ]
                                          }
                                    ]
                                }
                            ]
                        }
                    }
                },
                "tpaextensions": {
                    "cancellationTimeLimit": "2026-07-01T10:11:07Z",
                    "confirmationTimeLimit": "2025-07-01T10:40:55Z",
                    "updateTravellersTimeLimit": "2025-07-26T07:50:00Z"
                }
            }
  

• NOTE / LIMITATION: When a flight segment has been cancelled, no policy information will be returned for that segment.

Penalty rules are grouped by passengerTypeCode, such as ADT, CHD, or INF.

Field Descriptions

2026-06-28

Updated change passenger name type

• Updated document about change passenger name type (3) for AirBookModifyRQ.

2026-02-22

Clarify download all tickets endpoint (/tickets/confirmation/{rloc}/download)

• Updated the Download Tickets documentation to use rloc in the endpoint path instead of bookingReference (See more details)
• Documented optional mode query parameter for ticket ZIP download:
  • full (default)
  • delta
  • legacy (backward compatible alias for delta)
• Added request examples for default, full, and delta modes
• Added note that unsupported mode values return 400 Bad Request

2025-09-12

Segments cancellation with automatic refund

• Updated document add json schema for request, diagram and code snippet to explain how to build the payload request (See more details)

2025-07-11

Segments cancellation with automatic refund

• Added a new feature of cancellation based on flight segments with automatic refund. (See more details)

Add sold-out segment for OTA_AirLowFareSearchRS

• Flag attribute named “availableFlightOnly” to “false” in the OTA_AirLowfareSearchRQ to get sold-out segments in the response.

  {
    "availableFlightsOnly": false
  }
  

• Updated sample request and response to reflect actual structure (See more details)

• Updated error message when booking sold-out segment (See more details)

2025-07-02

Add policy for OTA_AirBookRS, OTA_AirPriceRS

• Add policy information in /airReservation/priceInfo/fareInfos/fareInfo/ruleInfo/tpaextensions.

            "fareInfos": {
                "fareInfo": [
                    {
                        "fareReference": [
                            {
                                "value": "EELMOWMC"
                            }
                        ],
                        "ruleInfo": {
                            "tpaextensions": {
                                "cancellationTimeLimit": "2026-07-01T10:11:07Z",
                                "confirmationTimeLimit": "2025-07-01T10:40:55Z",
                                "updateTravellersTimeLimit": "2025-07-26T07:50:00Z"
                            }
                        },
                        "filingAirline": {
                            "value": "HHR"
                        },
                        "marketingAirline": [],
                        "departureAirport": {
                            "locationCode": "JED"
                        },
                        "arrivalAirport": {
                            "locationCode": "DMX"
                        },
                        "date": [],
                        "fareInfo": [],
                        "city": [],
                        "airport": [],
                        "rph": "1"
                    }
                ]
            }
  

2025-06-26

Clarify request and response for AirLowFareSearch (one-way with booking class)

• Updated sample request and response to reflect actual structure and booking class usage (See more details)

2025-06-21

Deprecate download endpoint using passenger details and introduce the new one

• Introduced new endpoint to download specific ticket using ticketNumber and couponNumber
• Marked the existing endpoint using firstName, lastName, departure, and arrival as deprecated

Example

Deprecated Request Format:

curl '{base_url}/tickets/confirmation/{bookingReference}/download/passenger-segment?firstName=JENNIFER&lastName=STEWART&departure=MKX&arrival=DMX' \
    -H 'x-api-key: {api-key}' \
    --output ticket.pdf

New Request Format:

curl '{base_url}/tickets/confirmation/{bookingReference}/download/passenger-segment?ticketNumber=3333330292535&couponNumber=1' \
    -H 'x-api-key: {api-key}' \
    --output ticket.pdf

2025-04-23

Updated error response behavior documentation

The following changes in how errors are returned have been documented and moved from the main error-response guide:

• No train availability: External HHR used to return 204 No Content.
  • Before: API returned 404 Not Found.
  • After: API returns 200 OK with empty pricedItinerary.

  {
    "success": {},
    "pricedItineraries": {
      "pricedItinerary": []
    }
  }
  

• No price exists for the tariff: For mismatched flightNumber, fareBasis, or other criteria.
  • Before: API returned 400 Bad Request.
  • After: API returns 422 Unprocessable Entity with error details.

  {
    "status": 422,
    "error": "Unprocessable Entity",
    "code": "53",
    "title": "No price exists for the tariff",
    "detail": "No fare information match with the request",
    "correlationId": "e76b44e8-91e2-4fba-88d8-562a6ed7d755",
    "service": "ota-service",
    "instance": "/v2015b/OTA",
    "tenant": "test-skywork-dev",
    "timestamp": "2025-04-17T02:48:50.175504998Z",
    "cause": {
      "status": 422,
      "code": "53",
      "title": "No price exists for the tariff",
      "detail": "No fare information match with the request",
      "correlationId": "e76b44e8-91e2-4fba-88d8-562a6ed7d755",
      "service": "hhr-proxy",
      "instance": "/v2015b/OTA",
      "tenant": "test-skywork-dev",
      "timestamp": "2025-04-17T02:48:50.171876533Z"
    }
  }
  

• Service not Available: When HHR EBKS service is unavailable.
  • Before – GO7 adds whole content of external error and responds with 502 bad gateway
  • After – return the original error from the HHR EBKS system with its status, wrapped in our standard response structure (Problem JSON)

{
  "timestamp": "2025-01-13T09:12:24.574+00:00",
  "status": 502,
  "error": "Bad Gateway",
  "exception": "org.springframework.web.client.HttpServerErrorException$BadGateway",
  "message": "",
  "title": "",
  "correlationId": "a68ad759-daf5-48a2-bdaf-50c6c221a3a3",
  "service": "ota-service",
  "instance": "/v2015b/OTA",
  "tenant": "test-rs3",
  "cause": {
    "status": 502,
    "instance": "/reservations",
    "cause": {
      "title": "Bad Gateway",
      "status": 502,
      "detail": "503 Service Unavailable: \"",
      "instance": "/reservations",
      "cause": {
        "timestamp": "2025-04-13T06:25:20.652+00:00",
        "path": "/transport/api/v1/purchase",
        "status": 503,
        "error": "Service Unavailable",
        "requestId": "e1e1f214-407919"
      },
      "exception": "org.springframework.web.client.HttpServerErrorException$InternalServerError",
      "timestamp": "2025-01-13T09:12:24.549302606Z",
      "correlationId": "a68ad759-daf5-48a2-bdaf-50c6c221a3a3",
      "service": "hhr-proxy",
      "tenant": "test-rs3"
    },
    "tenant": "test-rs3",
    "service": "reservation-service",
    "correlationId": "a68ad759-daf5-48a2-bdaf-50c6c221a3a3",
    "message": "",
    "exception": "org.springframework.web.client.HttpServerErrorException$BadGateway",
    "error": "Bad Gateway",
    "timestamp": "2025-01-13T09:12:24.572+00:00"
  }
}
  

{
  "status": 503,
  "error": "Service Unavailable",
  "code": "450",
  "title": "Unable to process",
  "correlationId": "b1589271-9e52-4a57-98bf-6f05c6a15dbb",
  "service": "ota-service",
  "instance": "/v2015b/OTA",
  "tenant": "test-rs3",
  "timestamp": "2025-04-13T06:20:03.173515305Z",
  "cause": {
    "status": 503,
    "error": "Service Unavailable",
    "title": "",
    "correlationId": "b1589271-9e52-4a57-98bf-6f05c6a15dbb",
    "service": "reservation-service",
    "instance": "/reservations",
    "tenant": "test-rs3",
    "timestamp": "2025-04-13T06:20:03.170+00:00",
    "exception": "org.springframework.web.client.HttpServerErrorException$ServiceUnavailable",
    "cause": {
      "status": 503,
      "code": 0,
      "title": null,
      "correlationId": "b1589271-9e52-4a57-98bf-6f05c6a15dbb",
      "service": "hhr-proxy",
      "instance": "/reservations",
      "tenant": "test-rs3",
      "timestamp": "2025-04-13T06:20:03.163394791Z"
    },
    "message": ""
  }
}
  

• The error from external service (3rd party integration)

Note: The external error response will be formatted to our standard response structure (Problem JSON)

1. Before – GO7 wraps the original external error deeply nested in the cause tree and returns a 502 Bad Gateway
2. After – response is reformatted to standard Problem JSON structure with original error’s status, code, title, and detail

{
  "timestamp": "2025-01-13T09:12:24.574+00:00",
  "status": 502,
  "error": "Bad Gateway",
  "exception": "org.springframework.web.client.HttpServerErrorException$BadGateway",
  "message": "",
  "title": "",
  "correlationId": "a68ad759-daf5-48a2-bdaf-50c6c221a3a3",
  "service": "ota-service",
  "instance": "/v2015b/OTA",
  "tenant": "test-skywork-dev",
  "cause": {
    "status": 502,
    "instance": "/reservations",
    "cause": {
      "title": "Bad Gateway",
      "status": 502,
      "detail": "500 Internal Server Error: \"{\\\"code\\\":9999,\\\"message\\\":\\\"Unknown error\\\",\\\"details\\\":[{\\\"reason\\\":\\\"Could not commit JPA transaction\\\"}]}\"",
      "instance": "/reservations",
      "cause": {
        "details": [
          {
            "reason": "Could not commit JPA transaction"
          }
        ],
        "message": "Unknown error",
        "code": 9999
      },
      "exception": "org.springframework.web.client.HttpServerErrorException$InternalServerError",
      "timestamp": "2025-01-13T09:12:24.549302606Z",
      "correlationId": "a68ad759-daf5-48a2-bdaf-50c6c221a3a3",
      "service": "hhr-proxy",
      "tenant": "test-rs3"
    },
    "tenant": "test-skywork-dev",
    "service": "reservation-service",
    "correlationId": "a68ad759-daf5-48a2-bdaf-50c6c221a3a3",
    "message": "",
    "exception": "org.springframework.web.client.HttpServerErrorException$BadGateway",
    "error": "Bad Gateway",
    "timestamp": "2025-01-13T09:12:24.572+00:00"
  }
}
  

{
  "status": 500,
  "error": "Internal Server Error",
  "code": "9999",
  "title": "Unknown error",
  "detail": "Could not commit JPA transaction",
  "correlationId": "79f48120-952c-4ebe-b889-809c129932ee",
  "service": "ota-service",
  "instance": "/v2015b/OTA",
  "tenant": "test-skywork-dev",
  "timestamp": "2025-04-17T02:48:11.178912262Z",
  "cause": {
    "status": 500,
    "error": "Internal Server Error",
    "title": "Unknown error",
    "detail": "Could not commit JPA transaction",
    "correlationId": "79f48120-952c-4ebe-b889-809c129932ee",
    "service": "hhr-proxy",
    "instance": "/reservations",
    "tenant": "test-rs3",
    "timestamp": "2025-04-17T02:48:10.145711265Z"
  }
}
  

2025-04-16

Improved documents URLs in TPAExtension for OTA_AirDemandTicketRS and OTA_AirBookRS

To remove ambiguity in document download URLs and to simplify handling service responses, the links element has been added instead of the string field urls. The old field (urls) will remain for backward compatibility. The new field will contain the actual URL (href), a relation type (rel), and optional segmentRPH and travelerRPH.

 "links": [
    {
      "href" : "https://domain.com/tickets/download?ref=11",
      "rel" : "downloadTicket",
      "segmentRPH" : "1", // Optional
      "travelerRPH" : "1" // Optional
    }
  ]

    "tpaextensions": {
      "urls": "https://test-api.worldticket.net/sms-gateway-service/tickets/confirmation/QN6HQV/download/passenger-segment?firstName=JENNIFER&lastName=STEWART&departure=MKX&arrival=DMX https://test-api.worldticket.net/sms-gateway-service/tickets/confirmation/QN6HQV/download/passenger-segment?firstName=JENNIFER&lastName=STEWART&departure=DMX&arrival=MKX"
    }
  

    "tpaextensions": {
      "urls": "https://test-api.worldticket.net/sms-gateway-service/tickets/confirmation/QN6HQV/download/passenger-segment?firstName=JENNIFER&lastName=STEWART&departure=MKX&arrival=DMX https://test-api.worldticket.net/sms-gateway-service/tickets/confirmation/QN6HQV/download/passenger-segment?firstName=JENNIFER&lastName=STEWART&departure=DMX&arrival=MKX",
      "links": [
        {
          "href" : "https://test-api.worldticket.net/sms-gateway-service/tickets/confirmation/QN6HQV/download/passenger-segment?firstName=JENNIFER&lastName=STEWART&departure=MKX&arrival=DMX",
          "rel" : "downloadTicket",
          "segmentRPH" : "1",
          "travelerRPH" : "1"
        },
        {
          "href" : "https://test-api.worldticket.net/sms-gateway-service/tickets/confirmation/QN6HQV/download/passenger-segment?firstName=JENNIFER&lastName=STEWART&departure=DMX&arrival=MKX",
          "rel" : "downloadTicket",
          "segmentRPH" : "2",
          "travelerRPH" : "1"
        }
      ]
    }
  

Example

• See Response Payload (named passengers) in Payment and Ticketing
• See Response Payload in Read booking