Surcharges (Category 12) Rules Web Service

Surcharges (Category 12) Rules API is used to restrict a fare to a specific date or range of dates. The API is designed by ATPCO to meet your needs for automated table creation so you can reduce manual input and get your fares to market faster.

Request

Your request to the Surcharges (Category 12) Rules Web Service must provide a valid OAuth Access Token. For instructions on how to obtain and use an OAuth Access Token programmatically, see OAuth Access Tokens and Authentication. You must also specify parameters in the request body.

Request Header Parameters

See OAuth Access Tokens and Authentication for instructions on header parameters needed for authentication.

Request Body

The request body should be formatted as a JSON object (examples below).

Request Object Parameters

All data requests must be received in the JSON format specified by ATPCO, with field names and sub values found in Data Application unless otherwise specified (fields and sub values (i.e., parameters) detailed below). Field names and provided values must be enclosed in quotation marks (e.g., "tvlDtExp").

"" or " " as a field name or field value: an empty or non-empty blank string within quotation marks in the request is ignored and will not appear in the JSON response
Invalid field names in a request are ignored
Invalid field values in a request generate an error

If your request contains field names that are invalid in a request yet valid in a response (e.g., msgs or msg), those fields will be eliminated during processing and overlaid when necessary in the response.

All String fields (enclosed in double quotes) will have leading and trailing spaces removed unless removing all blanks would violate a possible value for a field where blank(s) is valid on a JSON request. Some fields may have special leading/trailing blanks removal rules such as NoteText996, where only trailing blanks are removed to preserve any intentional text indentations.

Field name	Value	Issue	System Handling
`" tvlDtExp"`		Extra leading space	ignored
`"tvlDtExp "`		Extra trailing space	ignored
`"tvlDExp"`		Field name incorrect. Missing 't'	ignored
	`" WAS"`	Extra leading space	Error invalid city format

Examples of Invalid Field names and values

The request object can include any of the following parameters:

Category 12 Parameters

Field name	Description	Type	Format	Example
`surcharges12`	Wrapper for Category 12 domain	Collection of key-value pairs		`{ }`
`firstDt`	The first date on which surcharge provisions are applicable	String	YYYYMMDD	`"20180930"`
`lastDt`	The last date on which surcharge provisions are applicable	String	YYYYMMDD	`"20180930"`
`firstTm`	The time of day when surcharge application is first valid	24 hour clock	`"0900"`
`lastTm`	The time of day when surcharge application is last valid	String	24 hour clock	`"0900"`
`dayRange`	A code specifying the application of start-stop times on the days of the week	String	`"R"` = Range; `"D"` = Day ;
`dayOfWeekItems`	An indicator specifying the day of week when travel is permitted	String	`"1"` = Monday; `"2"` = Tuesday; `"3"` = Wednesday; `"4"` = Thursday; `"5"` = Friday; `"6"` = Saturday; `"7"`= Sunday	"[`"01"`]"= Single Day; `"["1","3"]"`= Multiple Days
`surchargeType`	A code specifying the type of charge that is applicable	String	`" A"`= Airport/Terminal;`"B"` = Business Class;`"N"` = Navigation;`"D"` = Peak Travel Time;`"E"` = Equipment;`"F"` = Fuel; `"G"` = Peak;`"H"` = Holiday; `"I"` = Side Trip ; `"J"` = Seasonal;`"K"` = Weekend; `"L"` = Sleeperette;`"M"` = Waiver for Advance Purchase Req; `"O"` = Security;`"P"` = Waiver of Maximum Stay ; `"Q"` = Miscellaneous ; `"Z"` = RBD
`equipment`	A code specifying the equipment used if surcharge is based on aircraft type	String (max 3 alpha numeric character)		`"BUS"`
`feeAppliesPer`	Indicates a code indicating to which portion of travel the surcharge applies	String	`"1"`= Fare Component;`"2"` = Round Trip ;`"3"` = Transfer; `"4"` = Ticket; `"5"` = Coupon; `"6"` = Direction
`sectorPortion`	Indicates a code that specifies whether the Between/And Geographic specification table apply to a single sector or a portion of travel	String	`"S"` = Sector ;`"P"` = Portion
`chargesApplCd`	A code that indicates to whom the surcharge applies	String	`"AP"`=Per Any Passenger; `"CH"` = Per Child/Infant; `"AC"`="Per Adult/Child/Infant; `"AT"` = Per Adult. Child/Infant are discounted; `"BD"` = Per Adult
`amt1`	A number indicating the first surcharge amount	Numeric (max length 7 numerics plus one decimal)		`"1234567"` ; `"1234.56"`
`amt1Cur`	A code indicating the currency	String (max 3-character)	valid currency code	`"USD"`
`addSubtract`	A field that indicates if the value in Amount 1 should be a positive or a negative value	String	`"S"`= Subtract; `"A"`=Add
`amt2`	A number indicating the second surcharge amount	Numeric (max length 7 numerics plus one decimal)		`"1234567"` ; `"1234.56"`
`amt2Cur`	A code indicating the currency	String (max 3-character)	valid currency code	`"USD"`
`chargePercent`	The percentage to be applied to the surcharge	String (max 8-character)	8 numbers including a decimal (NNN.NNNN)	`"075.0000"`
`rbdCode`	A code indicating that the surcharge applies when travel is booked in this specified RBD	String (1-2 position alpha character)		`"bn"` ; `"n"`
`cxrFlt986`	indicates an existing carrier flight table number	Numeric (upto 8)		`"1234567"`

994 Override Date Fields

Field name	Description	Type	Format	Example
`ovrrdDt994`	Wrapper for 994 Subdomain	Collection of key-value pairs		`{ }`
`tvlEff`	The first date travel is valid for the Category Record 3 provisions	String	YYYYMMDD	`"20180930"`
`tvlDisc`	The last date travel is valid for the Category Record 3 provisions	String	YYYYMMDD	`"20180930"`
`tktEff`	The first date ticketing is valid for the Category Record 3 provisions	String	YYYYMMDD	`"20180930"`
`tktDisc`	The last date ticketing is valid for the Category Record 3 provisions	String	YYYYMMDD	`"20180930"`
`rsvEff`	The first date reservations can be made for the Category Record 3 provisions	String	YYYYMMDD	`"20180930"`
`rsvDisc`	The last date reservations can be made for the Category Record 3 provisions	String	YYYYMMDD	`"20180930"`

995 Travel Geographic Specification Fields

Field name	Description	Type	Format	Example
`tvlGeoTbl`	Wrapper for 995 Subdomain	Collection of key-value pairs		`{ }`
`type`	Indicates the type of geographic specified for the location or TSI for the Category Record 3 provisions	String (max 1-character)	`"A"` = Area; `"Z"` = Iata Zone ; `"S"` = State ;`"C"` = City ;`"P"` = Airport ;`"N"` = Nation
`loc1`	The first specified location valid for the Category Record 3 provisions	String max (5-character)	`"1"` = one digit numeric Area designator; `"210"` = 3 digit numeric assigned Iata Zone ; `"FL US"` = 5 digit including a space ;`"NYC"` = 3 digit alpha City code ;`"EWR"` = 3 digit alpha Airport code ;`"US"` = 2 digit alpha Iata Nation/Country code
`loc2`	The last specified location valid for the Category Record 3 provisions	String max (5-character)	`"1"` = one digit numeric Area designator; `"210"` = 3 digit numeric assigned Iata Zone ; `"FL US"` = 5 digit including a space ;`"C"` = 3 digit alpha City code ;`"P"` = 3 digit alpha Airport code ;`"N"` = 2 digit alpha Iata Nation/Country code
`tsi`	Travel Segment Indiator valid for the Record 3 provisions	String max 2 - (character)	`"03"` = 2 digit numeric TSI as defined

995 Between Geographic Specification Fields

Field name	Description	Type	Format	Example
`btwnGeoTbl`	Wrapper for 995 Subdomain	Collection of key-value pairs		`{ }`
`type`	Indicates the type of geographic specified for the location or TSI for the Category Record 3 provisions	String (max 1-character)	`"A"` = Area; `"Z"` = Iata Zone ; `"S"` = State ;`"C"` = City ;`"P"` = Airport ;`"N"` = Nation
`loc1`	The first specified location valid for the Category Record 3 provisions	String max (5-character)	`"1"` = one digit numeric Area designator; `"210"` = 3 digit numeric assigned Iata Zone ; `"FL US"` = 5 digit including a space ;`"NYC"` = 3 digit alpha City code ;`"EWR"` = 3 digit alpha Airport code ;`"US"` = 2 digit alpha Iata Nation/Country code
`loc2`	The last specified location valid for the Category Record 3 provisions	String max (5-character)	`"1"` = one digit numeric Area designator; `"210"` = 3 digit numeric assigned Iata Zone ; `"FL US"` = 5 digit including a space ;`"NYC"` = 3 digit alpha City code ;`"EWR"` = 3 digit alpha Airport code ;`"US"` = 2 digit alpha Iata Nation/Country code
`tsi`	Travel Segment Indiator valid for the Record 3 provisions	String max 2 - (character)	`"03"` = 2 digit numeric TSI as defined

995 And Geographic Specification Fields

Field name	Description	Type	Format	Example
`andGeoTbl`	Wrapper for 995 Subdomain	Collection of key-value pairs		`{ }`
`type`	Indicates the type of geographic specified for the location or TSI for the Category Record 3 provisions	String (max 1-character)	`"A"` = Area; `"Z"` = Iata Zone ; `"S"` = State ;`"C"` = City ;`"P"` = Airport ;`"N"` = Nation
`loc1`	The first specified location valid for the Category Record 3 provisions	String max (5-character)	`"1"` = one digit numeric Area designator; `"210"` = 3 digit numeric assigned Iata Zone ; `"FL US"` = 5 digit including a space ;`"NYC"` = 3 digit alpha City code ;`"EWR"` = 3 digit alpha Airport code ;`"US"` = 2 digit alpha Iata Nation/Country code
`loc2`	The last specified location valid for the Category Record 3 provisions	String max (5-character)	`"1"` = one digit numeric Area designator; `"210"` = 3 digit numeric assigned Iata Zone ; `"FL US"` = 5 digit including a space ;`"NYC"` = 3 digit alpha City code ;`"EWR"` = 3 digit alpha Airport code ;`"US"` = 2 digit alpha Iata Nation/Country code
`tsi`	Travel Segment Indiator valid for the Record 3 provisions	String max 2 - (character)	`"03"` = 2 digit numeric TSI as defined

996 Note Text

Field name	Description	Type	Format	Example
`noteTxt996`	Wrapper for 996 Table	Collection of key-value pairs		`{ }`
`txtLns`	Collection of lines of free-form text specified in the request	Array of collections of key-value pairs		`[ { "lnNum": "1", "txt": "THIS IS SAMPLE NOTE TEXT" }, ... ]`
`lnNum`	Line number indicating the placement of the associated `txt` field	String	#	`"1"`
`txt`	The text to be printed at the corresponding `lnNum` (line number)	String	Free-form text	`"THIS IS SAMPLE NOTE TEXT"`

General Fields

Field name	Description	Type	Format	Example
`rtnTblNumsOnly`	Indicates whether to display the created table numbers and the data values specified in the Request. When set to `"Y"` (True), ONLY the table numbers will display in the Response. Default is `"N"` (False).	String (max 1-character)	`"Y"` = True; `"N"` = False	`"N"`
`tblNum`	Indicates an existing 900 series table in a request or generated in a response when data has been created	String	#####	`"4035046"`

Response

Responses from the Surcharges (Category 12) Rules Web Service use the same parameters as requests, outlined above. Responses can also include msg and msgs, which are used to communicate error messages.

Example Requests and Responses

Simple Category Request

(display only table numbers in response)

request response

Copy

Copied

{
  "rtnTblNumsOnly":"Y",

   "surcharges12": {
      		"firstDt": "20190901",
		"lastDt": "20190905",
		"firstTm": "1201A",
		"lastTm": "1205N",
		"dayRange": "D",
		"dayOfWeekItems": ["01","02","03"] ,
		"surchargeType": "B",
		"equipment": "BUS",
		"feeAppliesPer":"1",
		"sectorPortion":"S",
		"tvlGeoTbl":"12345",
		"btwnGeoTbl":"2345",
		"andGeoTbl": "4567",
		"chargesApplCd":"1",
		"amt1":1234.34",
		"amt1Cur":"USD",
		"addSubtract" :"A",
		"amt2": "1234",
		"amt2Cur": "AED",
		"rbdCode": "bn",
		"cxrFlt986":"12345"
		}
}

Copy

Copied

{
  "rtnTblNumsOnly": "Y",
  "surcharges12": {
    "tblNum": "4035046"
  }
}

Simple Category Request with Supporting Table 994

(display table numbers and values in response)

request response

Copy

Copied

{
  "rtnTblNumsOnly":"N",

  "surcharges12": {
      		"firstDt": "20190901",
		"lastDt": "20190905",
		"firstTm": "1201A",
		"lastTm": "1205N",
		"dayRange": "D",
		"dayOfWeekItems": ["01","02","03"] ,
		"surchargeType": "B",
		"equipment": "BUS",
		"feeAppliesPer":"1",
		"sectorPortion":"S",
		"tvlGeoTbl":"12345",
		"btwnGeoTbl":"2345",
		"andGeoTbl": "4567",
		"chargesApplCd":"1",
		"amt1":1234.34",
		"amt1Cur":"USD",
		"addSubtract" :"A",
		"amt2": "1234",
		"amt2Cur": "AED",
		"rbdCode": "bn",
		"cxrFlt986":"12345",
		"ovrrdDt994": {
      		"rsvEff": "20180101"
    		}
 	 }
}

Copy

Copied

{
  "rtnTblNumsOnly": "N",
  "surcharges12": {
    "tblNum": "4034902",
  		"firstDt": "20190901",
		"lastDt": "20190905",
		"firstTm": "1201A",
		"lastTm": "1205N",
		"dayRange": "D",
		"dayOfWeekItems": ["01","02","03"] ,
		"surchargeType": "B",
		"equipment": "BUS",
		"feeAppliesPer":"1",
		"sectorPortion":"S",
		"tvlGeoTbl":"12345",
		"btwnGeoTbl":"2345",
		"andGeoTbl": "4567",
		"chargesApplCd":"1",
		"amt1":1234.34",
		"amt1Cur":"USD",
		"addSubtract" :"A",
		"amt2": "1234",
		"amt2Cur": "AED",
		"rbdCode": "bn",
		"cxrFlt986":"12345",
    "ovrrdDt994": {
      "tblNum": "58696",
      "rsvEff": "20180101"
    }
  }
}

Full Category Request

(display only table numbers in response)

request response

Copy

Copied

{
  "rtnTblNumsOnly":"Y",


 "surcharges12": {
      		"firstDt": "20190901",
		"lastDt": "20190905",
		"firstTm": "1201A",
		"lastTm": "1205N",
		"dayRange": "D",
		"dayOfWeekItems": ["01","02","03"] ,
		"surchargeType": "B",
		"equipment": "BUS",
		"feeAppliesPer":"1",
		"sectorPortion":"S",
		"chargesApplCd":"1",
		"amt1":1234.34",
		"amt1Cur":"USD",
		"addSubtract" :"A",
		"amt2": "1234",
		"amt2Cur": "AED",
		"rbdCode": "bn",
		"cxrFlt986":"12345",
    "ovrrdDt994": {
      "rsvEff": "20180101",
      "rsvDisc": "20180731",  
      "tktDisc": "20180731",
      "tvlEff": "20180201",
      "tvlDisc": "20181030"
    },
    "noteTxt996": {
      "txtLns": [{"lnNum":"1","txt": "THIS IS SAMPLE NOTE TEXT TO ILLUSTRATE"}
                ,{"lnNum":"2","txt": "          INDENTATION AND LINE BREAKS"}
                ,{"lnNum":"3","txt": "                IN YOUR REQUEST AND RESPONSE."}
                ,{"lnNum":"4","txt": "WE HOPE THAT YOU ARE ENJOYING OUR DEMO.."}]
    },
    "andGeoTbl": {
      "loc1": "SEA",
      "type": "C",
      "loc2": "MAD",
      "tsi": "01"
    },
    "btwnGeoTbl": {
      "loc1": "SEA",
      "type": "C",
      "loc2": "MAD",
      "tsi": "01"
    },
    "tvlGeoTbl" : {
      "loc1": "SEA",
      "type": "C",
      "loc2": "MAD",
      "tsi": "01"
    }
  }
}

Copy

Copied

{
  "rtnTblNumsOnly": "Y",
"surcharges12": {
 "tblNum": "4035073",
    "ovrrdDt994": {
      "tblNum": "58746"
    },      		
   "andGeoTbl": {
      "tblNum": "274619"
    },
    "btwnGeoTbl": {
      "tblNum": "274629"
    },
    "tvlGeoTbl" : {
      "tblNum": "274519"
    },
    "noteTxt996": {
      "tblNum": "8187666"
    }
  }
}

Simple Category Request Using Data and Existing Table Number

(display table number and values in response)

request response

Copy

Copied

{
  "rtnTblNumsOnly":"N",
 "surcharges12":  {
    "firstDt": "20190901",
		"lastDt": "20190905",
		"firstTm": "1201A",
		"lastTm": "1205N",
		"dayRange": "D",
		"dayOfWeekItems": ["01","02","03"] ,
		"surchargeType": "B",
		"equipment": "BUS",
		"feeAppliesPer":"1",
		"sectorPortion":"S",
		"chargesApplCd":"1",
		"amt1":1234.34",
		"amt1Cur":"USD",
		"addSubtract" :"A",
		"amt2": "1234",
		"amt2Cur": "AED",
		"rbdCode": "bn",
		"cxrFlt986":"12345",
    "ovrrdDt994": {
      "tblNum": "12345678",
    }
  }
}

Copy

Copied

{
  "rtnTblNumsOnly": "N",
 "surcharges12":  {
    "tblNum": "4034902",
   "firstDt": "20190901",
		"lastDt": "20190905",
		"firstTm": "1201A",
		"lastTm": "1205N",
		"dayRange": "D",
		"dayOfWeekItems": ["01","02","03"] ,
		"surchargeType": "B",
		"equipment": "BUS",
		"feeAppliesPer":"1",
		"sectorPortion":"S",
		"chargesApplCd":"1",
		"amt1":1234.34",
		"amt1Cur":"USD",
		"addSubtract" :"A",
		"amt2": "1234",
		"amt2Cur": "AED",
		"rbdCode": "bn",
		"cxrFlt986":"12345",
    "ovrrdDt994": {
      "tblNum": "12345678",
		
    }
  }
}