What is it?
The BagFeesGrid service retrieves information about the free baggage allowed to be taken aboard the plane and the potential charges applicable for additional baggage.
This service is paired with Sabre’s CalculateBagFees service, which is used as a bag charge calculation engine in Sabre check-in. It is based on ATPCO filing, enhanced by Sabre’s merchandising solutions.
Why use it?
This service is used to display information about baggage allowance for travelers within given reservation, and to apply charges for additional baggage on the itinerary. The baggage charges are returned in a strict layout (grids) allowing the application to reduce logic needed for proper charges selection.
How it works
This service analyzes the given reservation context and returns information about the baggage allowance and possible charges for each passenger.
The charges are returned in the form of a grid, displayed by POS in an ordered manner making it easier for the travelers to pick them.
How to use
Request
Follow one of the flows to obtain BagFeesGrid content:
PNR Locator
Displays baggage information for an existing reservation -
Prerequisites: The reservation (PNR) needs to be created, and an ATH token needs to be provided.
"requestType": "orderId",
"requestContext": {
"mode": "BOOKING",
"currency": "USD"
},
"orderReference": {
"orderType": "SABRE_PNR_LOCATOR",
"orderId": "RESLOC"
},
"resultsOnlyFor": {
"passengers": [
{
"id": "P1",
"referenceId": "1.1",
"ticketNumbers": [
"0453129227939",
"7959473492354C1",
"7959473492355C1"
]
}
],
"segments": [
{
"id": "S1",
"referenceId": "1",
"origin": "JFK",
"destination": "LAX",
"departure": "2020-10-20T22:34:44"
}
]
}
}
Payload
Prerequisites: None.
Create a request by providing all the required information. Include any non-required information such as passenger type code, fare details, or Frequent Flyer data whenever available.
"requestType": "payload",
"requestContext": {
"mode": "BOOKING",
"currency": "USD"
},
"reservation": {
"itinerary": {
"segments": [
{
"id": "S1",
"origin": "JFK",
"destination": "LAX",
"marketingDetails": {
"airline": "VA",
"flightNumber": "444",
"bookingCode": "Y"
},
"operatingDetails": {
"airline": "XX",
"flightNumber": "5",
"bookingCode": "X"
},
"departure": "2020-01-01T12:00:00",
"arrival": "2020-01-01T14:00:00",
"equipmentType": "737",
"actionCode": "HK",
"flown": true
},
{
"id": "S2",
"origin": "LAX",
"destination": "LAS",
"marketingDetails": {
"airline": "VA",
"flightNumber": "123",
"bookingCode": "Y"
},
"departure": "2020-01-15T12:00:00",
"arrival": "2020-01-15T13:00:00",
"equipmentType": "737",
"actionCode": "HK"
},
{
"id": "S3",
"origin": "LAS",
"destination": "JFK",
"marketingDetails": {
"airline": "VA",
"flightNumber": "234",
"bookingCode": "Y"
},
"departure": "2020-01-15T13:00:00",
"arrival": "2020-01-15T14:00:00"
}
]
},
"fares": [
{
"id": "F1",
"airline": "SU",
"brandCode": "BR",
"fareBasisCode": "JPASS8",
"ticketDesignator": "0BCD",
"fareRule": "BSPS",
"fareTariff": "304",
"fareType": "SAS",
"fareIndicator": 12,
"privateTariffIndicator": false,
"fareTypeBitmap": "0E",
"pricingVendorCode": "ATP"
}
],
"passengers": [
{
"id": "P1",
"type": "ADT",
"name": {
"prefix": "MR",
"first": "NATHAN",
"last": "SUMMERS",
"raw": "SUMMERS/NATHAN MR"
},
"loyaltyAccounts": [
{
"memberAirline": "EY",
"memberId": "X123"
},
{
"memberAirline": "VA",
"tier": {
"tag": "GLD"
}
},
{
"memberAirline": "VX",
"tier": {
"number": "1",
"numberType": "ATPCO"
}
}
],
"specialServices": [
{
"ssrCode": "ABCS",
"segmentRef": "S1"
},
{
"ssrCode": "DFAA"
},
{
"ssrCode": "GDGF",
"segmentRef": "S2"
},
{
"ssrCode": "GDGF"
},
{
"segmentRef": "S3"
}
],
"bookedAncillaries": [
{
"subcode": "ABC",
"airline": "EY",
"quantity": 2,
"segmentRefs": [
"S1"
],
"baggageSlotType": "STANDARD_PIECE",
"baggageSlotOccurences": [
1,
2
]
},
{
"subcode": "BCA",
"airline": "EY",
"quantity": 1,
"segmentRefs": [
"S1"
]
}
]
},
{
"id": "P2",
"type": "CHD",
"name": {
"prefix": "MS",
"first": "HOPE",
"last": "SUMMERS",
"raw": "SUMMERS/HOPE MS"
},
"specialServices": [
{
"ssrCode": "CHLD"
}
]
}
],
"pricedItineraries": [
{
"id": "PI1",
"passengerRefs": [
"P1",
"P2"
],
"ticketIssuanceDate": "2020-01-03",
"tourCode": "XASDEA",
"accountCodes": [
"ABCDE1",
"BCDEF2"
],
"fareComponents": [
{
"segmentRefs": [
"S1"
],
"fareRef": "F1",
"ticketedAllowance": "2PC"
},
{
"segmentRefs": [
"S2",
"S3"
],
"fareRef": "F1",
"ticketedAllowance": "2PC"
}
],
"itineraryParts": [
{
"segmentRefs": [
"S1"
]
},
{
"segmentRefs": [
"S2",
"S3"
]
}
]
}
]
},
"resultsOnlyFor": {
"passengerRefs": [
"P1"
],
"segmentRefs": [
"S2",
"S3"
]
}
}
Response
A successful response is returned with a HTTP status code 200.
The returned JSON payload contains two main sections: definitions
and offer
.
"definitions" : {
"segments": [...],
"passengers": [...],
"ancillaries": [...],
"rules": [...],
"pricedAncillaries": [...],
"allowedQuantities": [...]
},
"offer": {
"offerId": "ABCDX1234345345123",
"offerExpirationDateTime": "2020-05-01T12:30:00-01:00",
"baggageAllowance": [...],
"baggageGrids": [...]
}
}
Definitions and references
The definitions
section contains all the data definitions which can be further used in the response structure through references.
By convention, properties which are references to a definition are called with the Ref
suffix (or Refs
if the property holds an array of references).
The value in Ref
property is always the id
property of referenced data structure.
"definitions": {
"segments": [
{
"id": "S1", <1>
"origin": "JFK",
"destination": "LAS",
...
},
{
"id": "S2", <2>
"origin": "LAS",
"destination": "LAX",
...
}
],
"passengers": [...],
"ancillaries": [
{
"id": "A1", <3>
"commercialName": "1ST ADDITIONAL BAG AIRPORT",
"subcode": "0C3",
...
}
],
"pricedAncillaries": [
{
"id": "A1_1",
"ancillaryRef": "A1", <4>
"segmentRefs": [ <5>
"S1",
"S2"
],
"ancillaryFee": {
"totalFee": {
"base": {
"amount": {
"value": 30,
"currency": "USD"
}
},
...
}
}
}
],
...
- Segment definition with
id
property - Another segment definition with
id
property - Base ancillary data definition with
id
property - Reference to ancillary data defined earlier, by providing
id
value - References to segments data defined earlier, by providing
id
values
All the referenced element structures are located in the definitions
section so application consuming the service can unwind every reference if it parsed that block completely.
Quantity rules
The definitions section also lists definitions of rules for offer items quantities used in offer section.
{
"id": "single-item",
"perPassenger": {
"minimum": 1,
"maximum": 1
}
}
]
The above rule, if attached to an offer item, means that the POS cannot allow to select the item for a given passenger more than once.
Offer content
The returned offer comprises of four main elements:
- metadata properties for the offer itself (like expiration time)
- baggage allowance contaiing information about free baggage allowance eligible for passengers on defined journey segments
- baggage fees grids containing grouped information about applicable prices for bag pieces
- information about additional baggage charges which do not fit the grid concept
Metadata
The following properties of the offer
structure contain important information how to handle offers further.
offerId
is used to identify a persisted offering, it is required to be passed when booking an ancillary offer item (see <
offerExpirationDateTime
contains a timestamp, after which the offer returned would expire - meaning, the offer items won't be available to be booked anymore.
"definitions": { ... },
"offer": {
"offerId": "ABCDX1234345345123",
"offerExpirationDateTime": "2020-05-01T12:30:00-01:00",
...
}
}
Baggage Allowance
The baggage allowance section provides complete information on free baggage allowance for particular passengers and journey portions.
...
"baggageAllowance": [
{
"id": "ALL1",
"segmentRefs": [ <1>
"S1",
"S2"
],
"passengerRefs": [ <2>
"P1",
"P2"
],
"checkedInBaggage": { <3>
...
}
}
],
...
}
- The portion of travel it is applicable to by using a list of references to segment definitions (
segmentRefs
property). - The references for passenger definitions (
passengerRefs
property) specify which passenger are eligible for this allowance on a particular journey portion. - Specifies the actual allowance for checked-in baggage in place.
Checked-in Baggage Allowance
Checked-in baggage allowance can be defined using different baggage systems:
- PIECE, limiting the maximum number of baggage pieces, and additionally their individual type and weight or size limits.
- WEIGHT, limiting the total weight of all baggage pieces.
- WEIGHT_WITH_PIECE_LIMIT, limiting the total weight of all baggage pieces, with an additional restriction of maximum allowed baggage pieces.
Depending on the allowance system, different fields of checkedInBaggage
property would be used to describe all the applicable restrictions.
PIECE system limits
The maximum number of allowed baggage pieces is defined by the maxBaggagePieces
property.
The actual baggage piece types which can be considered toward this limit are defined through a list of allowedBaggageTypes
items.
These combine the baggage ancillary definitions and allowed number of such items within the maximum pieces constraint.
{
...
"checkedInBaggage": {
"allowanceSystem": "PIECE",
"limits": {
"maxBaggagePieces": 2,
"allowedBaggageTypes": [
{
"ancillaryRef": "A1",
"numberOfPieces": 2
},
{
"ancillaryRef": "A2",
"numberOfPieces": 1
},
]
}
}
}
],
In this example an eligible passenger is allowed to take maximum 2 pieces of baggage within their free allowance.
The types of these baggage pieces need to conform either to the A1
or the A2
ancillary definition.
Not every combination is allowed though, as restrictions on the number of pieces of different types still apply.
Here the passenger is allowed to take up-to 2 pieces of A1
and 1 piece of A2
within maximum of 2 pieces.
That allows for two combinations of baggage to fit within allowance: 2 x A1
or 1 x A1 + 1 x A2
.
WEIGHT system limits
Maximum total weight of allowed baggage is defined by the maxTotalWeight
list.
Each element of this list specifies a limit in a different weight unit.
{
...
"checkedInBaggage": {
"allowanceSystem": "WEIGHT",
"limits": {
"maxTotalWeight": [
{
"value": 35,
"unit": "KILOGRAM"
},
{
"value": 77,
"unit": "POUND"
}
]
}
}
}
],
In this example the eligible passenger is allowed to take a maximum of 35 kilograms (or 77 pounds) of baggage within allowance (regardless of the number of pieces).
WEIGHT_WITH_PIECE_LIMIT system limits
The maximum total weight of allowed baggage is defined by the maxTotalWeight
list.
Each element of this list specifies the limit in a different weight unit.
Additionally the number of baggage pieces counted towards weight allowance is restricted by the maxBaggagePieces
porperty.
{
...
"checkedInBaggage": {
"allowanceSystem": "WEIGHT_WITH_PIECE_LIMIT",
"limits": {
"maxBaggagePieces": 3,
"maxTotalWeight": [
{
"value": 35,
"unit": "KILOGRAM"
},
{
"value": 77,
"unit": "POUND"
}
]
}
}
}
}
],
In this example the eligible passenger is allowed to take a maximum of 35 kilograms (or 77 pounds) of baggage within allowance. This weight needs to be distributed over up to 3 baggage pieces.
Entitlements
Entitlements can enhance the original allowance. If the allowance definition has been enhanced by entitlement rules, additional properties would appear.
The limits
property would still contain actual limits.
Additionally originalLimits
can tell what was the base allowance which was enhanced.
On top of enhancing baggage types defined within the original allowance, entitlement can allow waiving the fee for a number of excess baggage pieces.
This is defined by the additionalBaggageFeeWaivers.maxPieces
property.
The types of baggage pieces which are eligible to a fee waiver are defined through additionalBaggageFeeWaivers.allowedBaggageTypes
.
{
...
"checkedInBaggage": {
"allowanceSystem": "PIECE",
"limits": {
"maxBaggagePieces": 1,
l {
"ancillaryRef": "A1E1",
"numberOfPieces": 1
}
]
},
"originalLimits": {
"maxBaggagePieces": 1,
"allowedBaggageTypes": [
{
"ancillaryRef": "A1",
"numberOfPieces": 1
}
]
},
"entitlement": {
"productModifierRef": "E1",
"additionalBaggageFeeWaivers": {
"maxPieces": 1,
"allowedBaggageTypes": [
{
"ancillaryRef": "A1E1",
"numberOfPieces": 1
}
]
}
}
}
}
],
In this example, eligible passenger instead to be allowed for a single piece of A1
baggage type, it is allowed to take A1E1
for free (possibly with enhanced weight limit).
Additionally, fee for the first excess piece of A1E1
would be also waived.
Rule definition referenced by E1
can allow to render information why entitlement has been granted.
Baggage Fees Grids
Baggage grid groups baggage charges for specific baggage journey and types into ordered columns. Each column represents a checked-in baggage item, like 1st bag, 2nd bag, etc.
Currently there are two types of "slottable" baggage charges:
STANDARD_PIECE
- representing fees for standard baggage pieces with different weight/size limitsNON_STANDARD_PIECE
- representing fees for non-standard baggage, like golf clubs or sport equipment...
"baggageGrids": [
{
"segmentRefs": [
"S1",
"S2"
],
"baggageSlotType": "STANDARD_PIECE",
"columns": [
{
"number": 1,
"allowance": [
{
"passengerRefs": [
"P1",
"P2"
],
"baggageAllowanceRef": "ALL1"
}
]
},
{
"number": 2,
"bookedItems": [
{
"passengerRefs": [
"P1"
],
"segmentRefs": [
"S1",
"S2"
],
"ancillaryRef": "A1"
}
],
"offerItems": [
{
"offerItemId": "GS1A2_1",
"pricedAncillaryRef": "A1_1",
"passengerRefs": [
"P2"
],
"allowedQuantityRef": "single-item"
}
]
},
{
"number": 3,
"offerItems": [
{
"offerItemId": "GS1A2_2",
"pricedAncillaryRef": "A1_2",
"passengerRefs": [
"P1",
"P2"
],
"allowedQuantityRef": "single-item"
},
{
"offerItemId": "GS1A2_3",
"pricedAncillaryRef": "A1_3"
"passengerRefs": [
"P1"
],
"allowedQuantityRef": "single-item"
}
]
}
]
}
...
This allows POS to implement simple rules around "slottable" baggage charges:
- Each passenger cannot select more than one eligible offer item from a given column.
- To pick an offer from a column, passenger needs to select items for every preceeding column
The preceding example shows a grid for standard baggage pieces for two passengers travelling over two segments (S1, S2). It could be presented in a form of a table:
Passenger | #1 Standard Bag | #2 Standard Bag | #3 Standard Bag | |
---|---|---|---|---|
P1 | free, within allowance (ALL1) | already purchased (A1) | two offer items available (A1_2 and A1_3) | |
P2 | free, within allowance (ALL1) | offer item available (A1_1) | offer item available (A1_2) |
In this example:
- POS needs to restrict passenger P1 to pick both offers from the third column (he can pick only one)
- POS needs to restrict passenger P2 to pick an offer item from the third column, unless he picks an offer item from the second column as well.
Other Baggage Fees
This section lists all the available baggage ancillaries which are not grouped into the grids.