My Profile
Sign Out
Tickets
Knowledge Base
Login
Articles in this section
Category / Section
  2. AGW Platform API v1.2

Special Fares

Published:

Introduction

We permit requests for special fares, such as Tour Operator or Corporate fares, with various airlines.

Each fare type requires different parameters based on the airline, fare, agency, and/or corporate entity. Therefore, each request must be specifically tailored to the required airline and fare.

Presets

In BookingPad, we have addressed this issue with Presets. Refer to our BookingPad help to understand its functionality. You can also use this feature in Sandbox with your tracer to simulate its behavior in your tools, as explained on our first steps page. Additionally, examples are provided in this article.

Besides using Presets in BookingPad, you can download your list of Presets (which must be set up via BookingPad, with support available upon request) using the following endpoint:
https://api.airgateway.work/v2.0/agent/access/agency/presets

This is a response example for that endpoint call (using your valid token):

[
...
{
       "title": "EXAMPLE",
       "airline": "AA",
       "travelers": [
           {
               "travelerType": "AAA",
               "defaultType": "ADT"
           },
           {
               "travelerType": "BBB",
               "defaultType": "YAD"
           },
           {
               "travelerType": "CCC",
               "defaultType": "CHD"
           },
           {
               "travelerType": "DDD",
               "defaultType": "INF"
           }
       ],
       "qualifier": {
           "type": "account_id",
           "code": "123",
           "airline": "AA"
       },
       "preference": [
           {
               "code": "759",
               "definition": "",
               "title": "Lowest Fares"
           },
           {
               "code": "758",
               "definition": "TOSD",
               "title": "Tour Operator Semi-Deferred"
           },
           {
               "code": "",
               "definition": "TD",
               "title": "Disney"
           }
       ],
       "preferences": [
           {
               "code": "-",
               "definition": "NO",
               "title": "No Preference"
           },
           {
               "code": "70J",
               "definition": "",
               "title": "Public Fares"
           },
           ...
           {
               "code": "749",
               "definition": "",
               "title": "Negotiated Fares"
           }
       ],
       "taxExemptions": [
           {
               "code": "XX"
           },
           {
               "code": "YY"
           }
       ],
       "isDefault": false,
       "isMandatory": false
   }
   ...
   ]

Inside presets, you can store:

  • Airline which that preset is available for
  • PTCs that preset can use
  • Preferences to be sent (code, definition and title)
  • Qualifier (type, code, airline)
  • Tax exeption (code of the tax they want to avoid)

If you want to use a Preset when calling AirShopping, you should send each of those values receive as follows.

Airline

This is straightforward. If a preset is configured for ‘AA,’ you should send the AirShopping request using the AG-Providers header with the value ‘AA’.

From the previous example:

"airline": "AA",

PTCs

Passenger Type Codes (PTCs) are more intricate to manage, primarily due to the frequent requirement of specifying the same four categories of PTCs, which include Adults, Young Adults, Children, and Infants. To streamline the process and enhance the ease of mapping these categories, we have introduced a ‘default’ option for each given PTC.

For instance:

"travelers": [
           {
               "travelerType": "AAA",
               "defaultType": "ADT"
           },
           {
               "travelerType": "BBB",
               "defaultType": "YAD"
           },
           {
               "travelerType": "CCC",
               "defaultType": "CHD"
           },
           {
               "travelerType": "DDD",
               "defaultType": "INF"
           }
       ],

To utilize this Preset for searching one adult and one child, we should use the following:

"passengers": 
[
 {
   "passengerType":  "AAA",
   "travelerReference":  "AAA0"
 },
 {
   "passengerType": "CCC",
   "travelerReference": "CCC0"
 }
],

Preferences

This section exhibits a significantly higher degree of heterogeneity. We have the capability to receive two distinct lists of preferences. The first list, referred to as ‘preferences,’ encompasses the entire collection of PADIS preferences and can be disregarded if necessary. The second list, termed ‘preference,’ pertains specifically to the current preset, which is the one of interest to us.

Within the ‘preference’ node, we have the potential to receive multiple preferences, each containing a code, definition, and title. It is important to note that none of these fields are compulsory. For instance:

"preference": [
           {
               "code": "759",
               "definition": "",
               "title": "Lowest Fares"
           },
           {
               "code": "758",
               "definition": "TOSD",
               "title": "Tour Operator Semi-Deferred"
           },
           {
               "code": "",
               "definition": "TD",
               "title": "Disney"
           }
       ],

The ‘Title’ is used solely to inform agents about the meaning of each preference. However, it is not necessary to receive it in the JSON API.

To utilize preferences from presets, they must be included in the preferences node. This includes the code (if available) and the definition (if available). For example:

"preferences": {
 "cabin": [
   "7"
 ],
 "fareList": [
   {
     "Code": "759",
     "Definition": ""
   },
   {
     "Code": "758",
     "Definition": "TOSD"
   },
   {
     "Definition": "TD"
   }
 ],
 "nonStop": false
},

In this case we’ve included the “Disney” preference, “Tour operator Semi Deferred”, including the code and the definition, and “Lowest Fare”, including only the code.

Qualifier

In this instance, we may receive three distinct fields: type, code, and airline. As illustrated in the example:

"qualifier": {
           "type": "account_id",
           "code": "123",
           "airline": "AA"
       },

Currently, the type supports three distinct values: account_id, contract_id, and promo_code.

This is straightforward to utilize:

"qualifier": {
 "airline": "AA",
 "code": "123",
 "type": "account_id"
},

Tax Exemption

We can now also request tax exemptions. This involves providing a list of codes that we can ask the airlines to exclude, as demonstrated in our example:

"taxExemptions": [
           {
               "code": "XX"
           },
           {
               "code": "YY"
           }
       ],

Incorporating these items into your AirShopping is straightforward; simply include them in the taxExemptions node.

"taxExemptions": [
 "XX",
 "YY"
]

Incorporating any preferences, qualifiers, or tax exemptions does not guarantee that the airline will provide such results or avoid taxes. Please consult with our support team and your airline account manager to determine the special fares available for your agency.

Examples

Copa Airlines

See an example in BookingPad in our help docs.

You can get Negociated fares with Copa by sending:

  • PTC = PFA
  • Preference = (749) Negociated Fares
  • Qualifier = Contract ID from the airline

British Airways

See an example in BookingPad in our help docs.

You can get many different fares with with British Airways. Please bear in mind that most of these fares depend on the agency and the route.

Tour Operator Fares

  • PTC = ITX
  • Preference = (758) Tour Operator Deferred

Tour Operator Semi-Deferred

  • PTC = TIM
  • Preference = (758) Tour Operator Semi-Deferred

Contract Bulk - Visiting Friends and Relatives

  • PTC = JCB
  • Preference = (758) Contract Bulk

Private Fare Adult

  • PTC = PFA
  • Preference = (758) Private Fare Adult

Humanitarian

  • PTC = MIS
  • Preference = (758) Private Fare Adult

Marine

  • PTC = SEA
  • Preference = (759) Lowest Fares, (758) Marine

Air France - KLM

See an example in BookingPad in our help docs.

Different fares can be retrieved for AF and KLM.

Tour Operator

  • PTC = IIT
  • Preference = (758) Tour Operator Deferred
  • Account ID = Account Id from the agency
{
  "metadata": {
    "country": "DE",
    "currency": "EUR",
    "locale": "de_DE"
  },
  "originDestinations": [
    {
      "arrival": {
        "airportCode": "PAR",
        "time": ""
      },
      "departure": {
        "airportCode": "LIS",
        "date": "2023-10-20",
        "time": ""
      }
    },
    {
      "arrival": {
        "airportCode": "LIS",
        "time": ""
      },
      "departure": {
        "airportCode": "PAR",
        "date": "2023-10-29",
        "time": ""
      }
    }
  ],
  "passengers": [
    {
      "passengerType": "ADT",
      "travelerReference": "ADT0"
    }
  ],
  "preferences": {
    "cabin": [
      "7"
    ],
    "fareList": [
      {
        "Code": "758",
        "Definition": "TOD"
      }
    ],
    "nonStop": false
  },
  "qualifier": {
    "airline": "AF",
    "code": "XXXXXX",
    "type": "account_id"
  }
}

Disney fares

  • Preference = Disney
  • Account ID = Account Id from the agency
{
  "metadata": {
    "country": "DE",
    "currency": "EUR",
    "locale": "de_DE"
  },
  "originDestinations": [
    {
      "arrival": {
        "airportCode": "PAR",
        "time": ""
      },
      "departure": {
        "airportCode": "MAD",
        "date": "2023-10-08",
        "time": ""
      }
    },
    {
      "arrival": {
        "airportCode": "MAD",
        "time": ""
      },
      "departure": {
        "airportCode": "PAR",
        "date": "2023-10-15",
        "time": ""
      }
    }
  ],
  "passengers": [
    {
      "passengerType": "ADT",
      "travelerReference": "ADT0"
    }
  ],
  "preferences": {
    "cabin": [
      "7"
    ],
    "fareList": [
      {
        "Definition": "TD"
      }
    ],
    "nonStop": false
  },
  "qualifier": {
    "airline": "AF",
    "code": "XXXXXX",
    "type": "account_id"
  }
}

Lufthansa

See an example in BookingPad in our help docs.

Different fares can be retrieved for Lufthansa.

Seaman / Marine Fares

  • PTC = SEA
  • Preference = (758) Marine

VFR

  • Preference = (758) Visit Friends & Family
  • Qualifier = Contract ID from the agency

Tour Operator

  • Preference = (758) Tour Operator Deferred
  • Qualifier = Contract ID from the agency

Student Fares

  • PTC = STU
  • Qualifier = Contract ID from the agency

Emirates

See an example in BookingPad in our help docs.

Negotiated fares

  • PTC = VFR
  • Preference = (749) Negotiated Fares

Singapore Airlines

See an example in BookingPad in our help docs.

We only accept Promo codes for now with Singapore Airlines.

Promo Codes

  • Qualifier = Promo code + promo code from the agency

Aegean

See an example in BookingPad in our help docs.

Negotiated fares

  • PTC = SEA
  • Preference = (758) Marine
Access denied
Access denied