NAV Navbar
Logo
json

Introduction

API version

v2.6

Welcome to the 30K Milefy API documentation!

Offline documentation

Looking for an offline version? Simply print this page as PDF. (Yes, you can do that, and it’ll look great.)

What does the Milefy API do?

You can use it to:

  1. Calculate frequent flyer earnings (miles) for specific flights,
  2. Learn which flights are eligible for mileage upgrades to a higher cabin, e.g. from Economy to Business
  3. Get a list of all frequent flyer benefits that apply for each flight based on the user’s frequent flyer program status tier.

Milefy API is a REST service using HTTPS protocole and JSON to encode both request and response data.

Request headers

To enforce proper request encoding and its compression you should always set following headers:

Authentication

Example of request authentication in C#

var bytes = Encoding.UTF8.GetBytes(                    
  string.Format("{0}:{1}", 
    _configuration.UserName, 
    _configuration.Password)
);

var base64AutorizationData = Convert.ToBase64String(bytes);

var webRequest = WebRequest.Create(url);

webRequest.Method = httpVerb;
webRequest.ContentType = "application/json";

webRequest.Headers.Add(
  HttpRequestHeader.AcceptEncoding, "gzip"
);

webRequest.Headers.Add(
  HttpRequestHeader.ContentEncoding, "utf-8"
);

webRequest.Headers.Add(
  HttpRequestHeader.Authorization, 
  string.Format("Basic {0}", base64AutorizationData)
);

We use SSL to transmit data from client to our service. You must authenticate client with HTTP Basic Authentication, which takes your login and password to form the request authentication header. This header must be sent with every request together with other headers.

Authorization header example

Authorization: Basic eW91cmxvZ2luOnlvdXJwYXNzd29yZA==

Version

Since version 2.5, we require the setting of an additional request header, which indicates which version of Milefy API you want to use. In case header is absent, version 2.4 will be used by default (not recommended).

Version header example

X-Api-Version: v2.6

Error handling

We use HTTP status codes listed in Appendix: HTTP status codes to handle general errors.

We also use internal status codes listed in Appendix: Status codes to indicate if request has been processed successfully.

In addition to that, majority of our methods, return in response a collection of error[] objects (e.g. CalculateMiles). These objects contain error codes listed in Appendix: Error codes as well as human-readable messages for debugging purposes.

Environments

Calculate method prepended with sample base service URL

GET https://milefyapi-client-xyz.30k.com/api/miles/programs

Testing

Used only for development and testing purposes. The Testing environment is usually slower than Live and may include less accurate results.

Live

You can switch to Live environment once your integration is verified by our team. Once that is done, you will receive the Live credentials. Accessing the Live environment ensures the best possible accuracy of calculation and performance.

Performance

Large flight result sets

When working with large flight result sets, it’s recommended to divide them into smaller batches and send them in simultaneous requests. When received, the multiple responses should then be remerged into a single result set. For example, instead of sending a single request containing a result set of 1,000 different flights, you can send 5 smaller requests simultaneously, each consisting of 200 flights.

All divided requests for the same result set are billed as only one request. In order to assure that, you only need to fulfill the following two conditions:

  1. All requests need to be send almost at the same time (we need to receive them within a frame of less than 30 seconds),
  2. The flights need to be split into chunks of 50-200 flights.

Mixed methods

The methods CalculateMixed and CalculateOneMixed are designed primarily for developer convenience, but they can have a slight impact on performance. To optimize your application for best performance, we recommend using the specific methods instead. For example, rather than using the CalculateMixed request to retrive frequent flyer earnings (miles) and benefits, it’s advisable to use the two separate methods instead (CalculateMiles and CalculateBenefits) and send two requests simultaneously. The two requests will be billed as a single one on also in this case.

Methods

Programs

The Programs method returns a list of all supported frequent flyer programs.

You can use the returned information in combination with any method that calculates frequent flyer miles, upgrades or benefits (for instance, the method CalculateMiles).

HTTP Request

GET /api/miles/programs

Request parameters

This method has no parameters.

Response structure

Sample response

{
  "Success": true,
  "Status":{
    "Code": 0,
    "Message": "OK"
  },
  "Value":[{
    "programCode": "UMP",
    "programName": "United Airlines MileagePlus",
    "helpUrl": "https://www.united.com/web/en-US/apps/account/settings/pin/pinResolution2.aspx",
    "signupUrl": "https://www.united.com/web/en-US/apps/account/enroll.aspx?sdl=sds&sdl=sd",
    "allianceCode": 4,
    "metrics":[{
      "metricCode": 1,
      "metricName": "Award Miles"
    },{
      "metricCode": 2,
      "metricName": "Premier Qualifying Miles"
    },{
      "metricCode": 3,
      "metricName": "Premier Qualifying Segments"
    },{
      "metricCode": 5,
      "metricName": "Premier Qualifying Dollars"
    }],
    "tiers":[{
      "tierCode": 1,
      "tierName": "Member"
    },{
      "tierCode": 8,
      "tierName": "Premier Silver"
    },{
      "tierCode": 16,
      "tierName": "Premier Gold"
    },{
      "tierCode": 24,
      "tierName": "Premier Platinum"
    },{
      "tierCode": 32,
      "tierName": "Premier 1K"
    }],
    "airlines": ["UA"]
  },{
    "programCode": "MAS",
    "programName": "Miles and Smiles",
    "helpUrl": "https://www4.thy.com/tkmiles/pinproblems.tk?lang=en",
    "signupUrl": "https://www4.thy.com/tkmiles/membersignin.tk?lang=en",
    "allianceCode": 4,
    "metrics":[{
      "metricCode": 1,
      "metricName": "Redeemable Miles"
    },{
      "metricCode": 2,
      "metricName": "Status miles"
    }],
    "tiers":[{
      "tierCode": 1,
      "tierName": "Classic"
    },{
      "tierCode": 8,
      "tierName": "Classic Plus"
    },{
      "tierCode": 16,
      "tierName": "Elite"
    },{
      "tierCode": 24,
      "tierName": "Elite Plus"
    }],
    "airlines": ["TK"]
  }]
}

Property Value Required Description
Success boolean Yes True if request has been executed successfully
Status object Yes Contains status of executed method
Status. Code integer Yes Response status code as in Appendix: Status codes.
Status. Message string Yes Human-readable message describing response status.
Value[] array No Contains list of frequent flyer programs. May be absent in case of error.
Value[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value[]. programName string Yes Full name of a frequent flyer program.
Value[]. helpUrl string No URL to password recovery page on program’s website. Useful to help users remind their password.
Value[]. siteUrl string No URL to program’s website.
Value[]. signupUrl string No URL to sign up page on program’s website.
Value[]. allianceCode integer Yes Code of alliance defined in Appendix: Alliances.
Value[]. metrics[] array Yes Collection of all accruals (types of miles) earned in this program.
Value[].metrics[]. metricCode integer Yes Code of accrual (type of earned miles) as listed in Appendix: Accrual types.
Value[].metrics[]. metricName string Yes Program-specific name of accrual (type of miles) intended for end-user interface usage.
Value[]. tiers[] array Yes Collection of all status tiers available in this program.
Value[].tiers[]. tierCode integer Yes Code of status tier as in Appendix: Status tiers.
Value[].tiers[]. tierName string Yes Program-specific name of status tier intended for end-user interface usage.
Value[]. airlines[] array Yes Collection of IATA codes of both owning and affiliated airlines of this program.

CalculateMiles

Sample request

{
  "flights": [{
    "flightId": "SK1674-SK0503|SK0502-SK0679",
    "price": {
      "currencyCode": "USD",
      "total": 150.0,
      "fare": 128.5
    },
    "legs":[{
      "segments": [{
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "TXL",
        "destCode": "CPH",
        "deptDate": "2016-07-02T09:35:00",
        "fareCode": "A",
        "flightNumber": 1674,
        "distance": 213
      },{
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "CPH",
        "destCode": "LHR",
        "deptDate": "2016-07-02T12:05:00",
        "fareCode": "A",
        "flightNumber": 503,
        "distance":610
      }]
    },{
      "segments":[{
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "LHR",
        "destCode": "CPH",
        "deptDate": "2016-07-16T09:50:00",
        "fareCode": "A",
        "flightNumber": 502,
        "distance": 610
      },{
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "CPH",
        "destCode": "TXL",
        "deptDate": "2016-07-16T15:05:00",
        "fareCode": "A",
        "flightNumber": 679,
        "distance": 213
      }]
    }]
  },{
    "flightId": "SK1674-SK0505|SK0502-SK0679",
    "price": {
      "currencyCode": "USD",
      "total": 750.0,
      "fare": 677.3
    },
    "legs": [{
      "segments": [{
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "TXL",
        "destCode": "CPH",
        "deptDate": "2016-07-02T09:35:00",
        "fareCode": "A",
        "flightNumber": 1674,
        "distance": 213
      },{
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "CPH",
        "destCode": "LHR",
        "deptDate": "2016-07-02T14:50:00",
        "fareCode": "A",
        "flightNumber": 505,
        "distance": 610
      }]
    },{
      "segments": [{
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "LHR",
        "destCode": "CPH",
        "deptDate": "2016-07-16T09:50:00",
        "fareCode": "A",
        "flightNumber": 502,
        "distance": 610
      },{
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "CPH",
        "destCode": "TXL",
        "deptDate": "2016-07-16T15:05:00",
        "fareCode": "A",
        "flightNumber": 679,
        "distance": 213
      }]
    }]
  }],
  "programs": [{
    "programCode": "SEB",
    "tierCode": 8
  }],
  "clientUserId": "0000001internal"
}

The CalculateMiles method returns the eligible frequent flyer earnings (miles), as calculated, for all flights in a request.

You can specify frequent flyer programs to personalize the calculations in the response based on a user’s program memberships. If you don’t specify, the earnings will be calculated and returned according to the frequent flyer program of the marketing carrier of each flight. For example if marketing carrier is Delta, earnings will be returned for Delta SkyMiles program.

HTTP Request

POST /api/miles/calculate

Request parameters

Should be sent as the body of a request in JSON format.

Property Value Required Description
flights[] array Yes Collection of flights for which miles will be calculated.
flights[]. flightId string Yes Unique id of the flight used as a reference in API response
flights[]. legs[] array Yes Collection of flight legs. Flight leg may contain a few flight segments separated by layovers. Round-trip flight consists of two flight legs.
flights[].legs[]. segments[] array Yes Collection of flight segments. Flight segment is characterized by single takeoff and landing.
flights[].legs[].segments[]. marketingAirlineCode string Yes IATA code (two characters) of the marketing (selling) airline.
flights[].legs[].segments[]. operatingAirlineCode string Yes IATA code (two characters) of the operating (owning the aircraft) airline.
flights[].legs[].segments[]. deptCode string Yes IATA code (three letters) of the departure airport.
flights[].legs[].segments[]. destCode string Yes IATA code (three letters) of the destination airport.
flights[].legs[].segments[]. deptDate string Yes Date in ISO-8601 format e.g. MM/DD/YYYY, YYYY-MM-DD or YYYY-MM-DDThh:mm:ss. Time is not required.
flights[].legs[].segments[]. fareCode string Yes Single letter code also known as booking code or Reservation Booking Designator (RBD).
flights[].legs[].segments[]. flightNumber string Yes Flight number without airline code prefix. In other words just digits e.g. 3861.
flights[].legs[].segments[]. distance integer No Flown distance in land miles rounded to whole mile. If absent, the shortest distance between two airports will be calculated instead. Recommended to ensure best accuracy.
flights[]. price object No Required to ensure correct calculations for revenue-based frequent flyer programs. Strongly recommended.
flights[].price. currencyCode string Yes ISO-4217 3-letter currency code
flights[].price. total double Yes Total fare price for entire flight including taxes, fees, surcharges etc.
flights[].price. fare double No Base fare price. Recommended to ensure best accuracy for revenue-based frequent flyer programs.
flights[].price. taxes double No Total amount for all taxes.
flights[].price. surcharges double No Total amount of surcharges imposed by the carrier.
programs[] array No Collection of frequent flyer program objects for which you want to calculate miles. Used to personalize results based on user memberships.
programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs. You can request list of programs with their codes using Programs method.
programs[]. tierCode integer No Code of status tier for specified frequent flyer program as in Appendix: Status tiers. Used to personalize calculations for users holding special status tier in a program e.g. Silver Status. If not specified, default, basic status tier will be used.
clientUserId string No Unique user id to link subsequent requests to the same person. Strongly recommended.

Response structure

Sample response

{
  "Success": true,
  "Status": {
    "Code": 0,
    "Message": "OK"
  },
  "Value": {
    "uniqueId": "56cbd707-66de-4b94-a132-4a7650ed3c67",
    "flights": [{
      "flightId": "SK1674-SK0503|SK0502-SK0679",
      "programs": [{
        "programCode": "SEB",
        "tierCode": 8,
        "earnings": [{
          "metricCode": 1,
          "value": 6000
        },{
          "metricCode": 2,
          "value": 6000
        },{
          "metricCode": 3,
          "value": 4
        }]
      }]
    },{
      "flightId": "SK1674-SK0505|SK0502-SK0679",
      "programs": [{
        "programCode": "SEB",
        "tierCode": 8,
        "earnings": [{
          "metricCode": 1,
          "value": 6000
        },{
          "metricCode": 2,
          "value": 6000
        },{
          "metricCode": 3,
          "value": 4
        }]
      }]
    }],
    "programs": [{
      "programCode": "SEB"
    }],
    "errors": []
  }
}

Property Value Required Description
Success boolean Yes True if request has been executed successfully
Status object Yes Contains status of executed method
Status. Code integer Yes Response status code as in Appendix: Status codes.
Status. Message string Yes Human-readable message describing response status.
Value object No Contains frequent flyer earnings (miles) for specified (or default) pairs of frequent flyer program and status tier. May be absent in case of error.
Value. uniqueId string Yes Unique id generated for every request.
Value. flights[] array Yes Collection of flights containing frequent flyer earnings.
Value.flights[]. flightId string Yes Unique id of the flight specified in request.
Value.flights[]. programs[] array No Collection of objects with frequent flyer earnings (miles) for particular frequent flyer program and its certain status tier. It reflects fact, that one flight can potentially earn miles to many programs.
Value.flights[].programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value.flights[].programs[]. tierCode integer Yes Code of status tier for specified frequent flyer program as in Appendix: Status tiers. By default only basic status tier is returned.
Value.flights[].programs[]. earnings[] array Yes Collection of objects with frequent flyer earnings (miles). Each object contains earnings for different accrual (type of earned miles).
Value.flights[].programs[].earnings[]. metricCode integer Yes Code of accrual (type of earned miles) as listed in Appendix: Accrual types.
Value.flights[].programs[].earnings[]. value double Yes Number of earned frequent flyer miles or points. In some cases it may be a decimal.
Value. programs[] array Yes Collection of basic information about frequent flyer programs used in response. For more detailed information and full list of programs, you need to use Programs method. Array may be empty if there were no programs earning to any of specified flights.
Value.programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value. errors[] array Yes Collection of error objects for specific flights (if any occured).
Value.errors[]. flightId string Yes Unique id of the flight specified in request.
Value.errors[]. code string Yes Error code indicating problem encountered when processing flight information in request. See all error codes listed in Appendix: Error codes.
Value.errors[]. message string Yes Human-readable message for debugging purposes.

CalculateOneMiles

Sample request

{
    "flight": {
        "flightId": "SK1674-SK0503|SK0502-SK0679",
        "price": {
            "currencyCode": "USD",
            "total": 128.5,
            "fare": 128.5
        },
        "legs": [{
            "segments": [{
                "marketingAirlineCode": "SK",
                "operatingAirlineCode": "SK",
                "deptCode": "TXL",
                "destCode": "CPH",
                "deptDate": "2016-07-02T09:35:00",
                "fareCode": "A",
                "flightNumber": 1674,
                "distance": 213
            }, {
                "marketingAirlineCode": "SK",
                "operatingAirlineCode": "SK",
                "deptCode": "CPH",
                "destCode": "LHR",
                "deptDate": "2016-07-02T12:05:00",
                "fareCode": "A",
                "flightNumber": 503,
                "distance": 610
            }]
        }, {
            "segments": [{
                "marketingAirlineCode": "SK",
                "operatingAirlineCode": "SK",
                "deptCode": "LHR",
                "destCode": "CPH",
                "deptDate": "2016-07-16T09:50:00",
                "fareCode": "A",
                "flightNumber": 502,
                "distance": 610
            }, {
                "marketingAirlineCode": "SK",
                "operatingAirlineCode": "SK",
                "deptCode": "CPH",
                "destCode": "TXL",
                "deptDate": "2016-07-16T15:05:00",
                "fareCode": "A",
                "flightNumber": 679,
                "distance": 213
            }]
        }]
    },
    "applyAllPrograms": true,
    "clientUserId": "Internal000001"
}

CalculateOneMiles method returns frequent flyer earnings (miles) for a single flight.

In contrast with CalculateMiles method, you can return earnings for all applicable frequent flyer program and their status tiers by setting applyAllPrograms flag as true.

HTTP Request

POST /api/miles/calculateone

Request parameters

Should be sent as the body of a request in JSON format.

Property Value Required Description
flight object Yes Flight for which miles will be calculated.
flight. flightId string Yes Unique id of the flight used as a reference in API response
flight. legs[] array Yes Collection of flight legs. Flight leg may contain a few flight segments separated by layovers. Round-trip flight consists of two flight legs.
flight.legs[]. segments[] array Yes Collection of flight segments. Flight segment is characterized by single takeoff and landing.
flight.legs[].segments[]. marketingAirlineCode string Yes IATA code (two characters) of the marketing (selling) airline.
flight.legs[].segments[]. operatingAirlineCode string Yes IATA code (two characters) of the operating (owning the aircraft) airline.
flight.legs[].segments[]. deptCode string Yes IATA code (three letters) of the departure airport.
flight.legs[].segments[]. destCode string Yes IATA code (three letters) of the destination airport.
flight.legs[].segments[]. deptDate string Yes Date in ISO-8601 format e.g. MM/DD/YYYY, YYYY-MM-DD or YYYY-MM-DDThh:mm:ss. Time is not required.
flight.legs[].segments[]. fareCode string Yes Single letter code also known as booking code or Reservation Booking Designator (RBD).
flight.legs[].segments[]. flightNumber string Yes Flight number without airline code prefix. In other words just digits e.g. 3861.
flight.legs[].segments[]. distance integer No Flown distance in land miles rounded to whole mile. If absent, the shortest distance between two airports will be calculated instead. Recommended to ensure best accuracy.
flight. price object No Required to ensure correct calculations for revenue-based frequent flyer programs. Strongly recommended.
flight.price. currencyCode string Yes ISO-4217 3-letter currency code
flight.price. total double Yes Total fare price for entire flight including taxes, fees, surcharges etc.
flight.price. fare double No Base fare price. Recommended to ensure best accuracy for revenue-based frequent flyer programs.
flight.price. taxes double No Total amount for all taxes.
flight.price. surcharges double No Total amount of surcharges imposed by the carrier.
programs[] array No Collection of frequent flyer program objects for which you want to calculate miles. Used to personalize results based on user memberships.
programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs. You can request list of programs with their codes using Programs method.
programs[]. tierCode integer No Code of status tier for specified frequent flyer program as in Appendix: Status tiers. Used to personalize calculations for users holding special status tier in a program e.g. Silver Status. If not specified, default, basic status tier will be used.
applyAllPrograms boolean No If set true and programs[] array is absent or empty, then all applicable combinations of frequent flyer program and its status tiers will be returned (not only pair of default program and basic status tier as in CalculateMiles method).
clientUserId string No Unique user id to link subsequent requests to the same person. Strongly recommended.

Response structure

Sample response

{
  "Success": true,
  "Status": {
    "Code": 0,
    "Message": "OK"
  },
  "Value": {
    "uniqueId": "56cbd707-66de-4b94-a132-4a7650ed3c67",
    "flights": [{
      "flightId": "SK1674-SK0503|SK0502-SK0679",
      "programs": [{
        "programCode": "SEB",
        "tierCode": 1,
        "earnings": [{
          "metricCode": 1,
          "value": 6000
        },{
          "metricCode": 2,
          "value": 6000
        },{
          "metricCode": 3,
          "value": 4
        }]
      },{
        "programCode": "SEB",
        "tierCode": 8,
        "earnings": [{
          "metricCode": 1,
          "value": 12000
        },{
          "metricCode": 2,
          "value": 12000
        },{
          "metricCode": 3,
          "value": 4
        }]
      },{
        "programCode": "ACA",
        "tierCode": 1,
        "earnings": [{
          "metricCode": 1,
          "value": 5000
        },{
          "metricCode": 2,
          "value": 5000
        }]
      }]
    }],
    "programs": [{
      "programCode": "SEB"
    },{
      "programCode": "ACA"
    }],
    "errors": []
  }
}

Property Value Required Description
Success boolean Yes True if request has been executed successfully
Status object Yes Contains status of executed method
Status. Code integer Yes Response status code as in Appendix: Status codes.
Status. Message string Yes Human-readable message describing response status.
Value object No Contains frequent flyer earnings (miles) for specified (or default) pairs of frequent flyer program and status tier. May be absent in case of error.
Value. uniqueId string Yes Unique id generated for every request.
Value. flights[] array Yes Collection of flights containing frequent flyer earnings.
Value.flights[]. flightId string Yes Unique id of the flight specified in request.
Value.flights[]. programs[] array No Collection of objects with frequent flyer earnings (miles) for particular frequent flyer program and its certain status tier. It reflects fact, that one flight can potentially earn miles to many programs.
Value.flights[].programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value.flights[].programs[]. tierCode integer Yes Code of status tier for specified frequent flyer program as in Appendix: Status tiers. By default only basic status tier is returned.
Value.flights[].programs[]. earnings[] array Yes Collection of objects with frequent flyer earnings (miles). Each object contains earnings for different accrual (type of earned miles).
Value.flights[].programs[].earnings[]. metricCode integer Yes Code of accrual (type of earned miles) as listed in Appendix: Accrual types.
Value.flights[].programs[].earnings[]. value double Yes Number of earned frequent flyer miles or points. In some cases it may be a decimal.
Value. programs[] array Yes Collection of basic information about frequent flyer programs used in response. For more detailed information and full list of programs, you need to use Programs method. Array may be empty if there were no programs earning to any of specified flights.
Value.programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value. errors[] array Yes Collection of error objects for specific flights (if any occured).
Value.errors[]. flightId string Yes Unique id of the flight specified in request.
Value.errors[]. code string Yes Error code indicating problem encountered when processing flight information in request. See all error codes listed in Appendix: Error codes.
Value.errors[]. message string Yes Human-readable message for debugging purposes.

CalculateUpgrades

Sample request

{
  "flights": [{
    "flightId": "SK1674-SK0503|SK0502-SK0679",
    "price": {
      "currencyCode": "USD",
      "total": 150.0,
      "fare": 128.5,
      "surcharges": 11.5,
      "taxes": 10
    },
    "legs":[{
      "legId": "SK1674-SK0503",
      "segments": [{
        "segmentId": "SK1674",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "TXL",
        "destCode": "CPH",
        "deptDate": "2016-07-02T09:35:00",
        "fareCode": "A",
        "flightNumber": 1674,
        "distance": 213
      },{
        "segmentId": "SK0503",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "CPH",
        "destCode": "LHR",
        "deptDate": "2016-07-02T12:05:00",
        "fareCode": "A",
        "flightNumber": 503,
        "distance":610
      }]
    },{
      "legId": "SK0502-SK0679",
      "segments": [{
        "segmentId": "SK0502",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "LHR",
        "destCode": "CPH",
        "deptDate": "2016-07-16T09:50:00",
        "fareCode": "A",
        "flightNumber": 502,
        "distance": 610
      },{
        "segmentId": "SK0679",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "CPH",
        "destCode": "TXL",
        "deptDate": "2016-07-16T15:05:00",
        "fareCode": "A",
        "flightNumber": 679,
        "distance": 213
      }]
    }]
  }],
  "programs": [{
    "programCode": "AKF",
    "tierCode": 1
  }],
  "clientUserId": "0000001internal"
}

The CalculateUpgrades method returns the eligibility for a cabin upgrade of flight segments and legs, e.g. from Economy to Business.

In order to retrieve the redemption cost (in redeeemable miles) of an upgrade, use the CalculateOneUpgrades method.

HTTP Request

POST /api/upgrades/calculate

Request parameters

Should be sent as the body of a request in JSON format.

Property Value Required Description
flights[] array Yes Collection of flights for which upgrade eligibility will be calculated.
flights[]. flightId string Yes Unique id of the flight used as a reference in API response.
flights[]. legs[] array Yes Collection of flight legs. Flight leg may contain a few flight segments separated by layovers. Round-trip flight consists of two flight legs.
flights[].legs[]. legId string No Unique id of the flight leg used as a reference in API response. Will be generated if absent.
flights[].legs[]. segments[] array Yes Collection of flight segments. Flight segment is characterized by single takeoff and landing.
flights[].legs[].segments[]. segmentId string No Unique id of the flight segment used as a reference in API response. Will be generated if absent.
flights[].legs[].segments[]. marketingAirlineCode string Yes IATA code (two characters) of the marketing (selling) airline.
flights[].legs[].segments[]. operatingAirlineCode string Yes IATA code (two characters) of the operating (owning the aircraft) airline.
flights[].legs[].segments[]. deptCode string Yes IATA code (three letters) of the departure airport.
flights[].legs[].segments[]. destCode string Yes IATA code (three letters) of the destination airport.
flights[].legs[].segments[]. deptDate string Yes Date in ISO-8601 format e.g. MM/DD/YYYY, YYYY-MM-DD or YYYY-MM-DDThh:mm:ss. Time is not required.
flights[].legs[].segments[]. fareCode string Yes Single letter code also known as booking code or Reservation Booking Designator (RBD).
flights[].legs[].segments[]. flightNumber string Yes Flight number without airline code prefix. In other words just digits e.g. 3861.
flights[].legs[].segments[]. distance integer No Flown distance in land miles rounded to whole mile. If absent, the shortest distance between two airports will be calculated instead. Recommended to ensure best accuracy.
flights[]. price object No Required to ensure correct calculations for revenue-based frequent flyer programs. Strongly recommended.
flights[].price. currencyCode string Yes ISO-4217 3-letter currency code
flights[].price. total double Yes Total fare price for entire flight including taxes, fees, surcharges etc.
flights[].price. fare double No Base fare price. Recommended to ensure best accuracy for revenue-based frequent flyer programs.
flights[].price. taxes double No Total amount for all taxes.
flights[].price. surcharges double No Total amount of surcharges imposed by the carrier.
programs[] array No Collection of frequent flyer program objects for which you want to calculate upgrades eligibility. Used to personalize results based on user memberships.
programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs. You can request list of programs with their codes using Programs method.
programs[]. tierCode integer No Code of status tier for specified frequent flyer program as in Appendix: Status tiers. Used to personalize calculations for users holding special status tier in a program e.g. Silver Status. If not specified, default, basic status tier will be used.
clientUserId string No Unique user id to link subsequent requests to the same person. Strongly recommended.

Response structure

Sample response

{
  "Success": true,
  "Status": {
    "Code": 0,
    "Message": "OK"
  },
  "Value": {
    "uniqueId": "56cbd707-66de-4b94-a132-4a7650ed3c67",
    "flights": [{
      "flightId": "SK1674-SK0503|SK0502-SK0679",
      "programs": [{
        "programCode": "AKF",
        "tierCode": 1,
        "options": [{
            "targetFareType": 48,
            "details": [{
                "targetId": "SK1674-SK0503",
                "legLevel": true
            }]
        }]
      }]
    }],
    "programs": [{
      "programCode": "AKF"
    }],
    "errors": []
  }
}

Property Value Required Description
Success boolean Yes True if request has been executed successfully
Status object Yes Contains status of executed method
Status. Code integer Yes Response status code as in Appendix: Status codes.
Status. Message string Yes Human-readable message describing response status.
Value object No Contains cabin upgrade options for each specified flight and combinations of frequent flyer program and status tier pairs (if set in request). May be absent in case of error.
Value. uniqueId string Yes Unique id generated for every request.
Value. flights[] array Yes Collection of flights containing upgrade eligibility information.
Value.flights[]. flightId string Yes Unique id of the flight specified in request.
Value.flights[]. programs[] array No Collection of objects with cabin upgrade options for particular frequent flyer program and its certain status tier. It reflects fact, that one flight leg or segment can potentially be upgraded with redeemable miles from different programs.
Value.flights[].programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value.flights[].programs[]. tierCode integer Yes Code of status tier for specified frequent flyer program as in Appendix: Status tiers. By default only basic status tier is returned.
Value.flights[].programs[]. options[] array Yes Collection of cabin upgrade options e.g. upgrade to Economy is one option, upgrade to Business is another.
Value.flights[].programs[].options[]. targetFareType integer Yes Code of target fare type (cabin) as listed in Appendix: Fare families.
Value.flights[].programs[].options[]. details[] array Yes Collection of upgrade objects for particular, eligible flight leg and/or segment.
Value.flights[].programs[].options[].details[]. targetId string Yes Unique id of flight leg or segment specified in request (or generated if absent). Indicates which fragment of entire flight is eligible for an upgrade.
Value.flights[].programs[].options[].details[]. legLevel boolean Yes True if targetId field relates to flight leg. False if it relates to flight segment.
Value. programs[] array Yes Collection of basic information about frequent flyer programs used in response. For more detailed information and full list of programs, you need to use Programs method. Array may be empty if there were no upgrade options available for any of specified flights.
Value.programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value. errors[] array Yes Collection of error objects for specific flights (if any occured).
Value.errors[]. flightId string Yes Unique id of the flight specified in request.
Value.errors[]. code string Yes Error code indicating problem encountered when processing flight information in request. See all error codes listed in Appendix: Error codes.
Value.errors[]. message string Yes Human-readable message for debugging purposes.

CalculateOneUpgrades

Sample request

{
  "flight": {
    "flightId": "SK1674-SK0503",
    "price": {
      "currencyCode": "USD",
      "total": 150.0,
      "fare": 128.5,
      "surcharges": 11.5,
      "taxes": 10
    },
    "legs":[{
      "legId": "SK1674-SK0503",
      "segments": [{
        "segmentId": "SK1674",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "TXL",
        "destCode": "CPH",
        "deptDate": "2016-07-02T09:35:00",
        "fareCode": "A",
        "flightNumber": 1674,
        "distance": 213
      },{
        "segmentId": "SK0503",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "CPH",
        "destCode": "LHR",
        "deptDate": "2016-07-02T12:05:00",
        "fareCode": "A",
        "flightNumber": 503,
        "distance":610
      }]
    }]
  },
  "clientUserId": "0000001internal"
}

The CalculateOneUpgrades method returns the cost of the cabin upgrade (e.g. from Economy to Business) in redeemable miles. The cost will be returned either per segment or per leg, as applicable for each frequent flyer program.

In contrast with the CalculateUpgrades method, you can return upgrade eligibility for all applicable frequent flyer programs and their status tiers by setting applyAllPrograms flag as true.

HTTP Request

POST /api/upgrades/calculateone

Request parameters

Should be sent as the body of a request in JSON format.

Property Value Required Description
flight object Yes Flight for which upgrade eligibility and cost will be calculated.
flight. flightId string Yes Unique id of the flight used as a reference in API response.
flight. legs[] array Yes Collection of flight legs. Flight leg may contain a few flight segments separated by layovers. Round-trip flight consists of two flight legs.
flight.legs[]. legId string No Unique id of the flight leg used as a reference in API response. Will be generated if absent.
flight.legs[]. segments[] array Yes Collection of flight segments. Flight segment is characterized by single takeoff and landing.
flight.legs[].segments[]. segmentId string No Unique id of the flight segment used as a reference in API response. Will be generated if absent.
flight.legs[].segments[]. marketingAirlineCode string Yes IATA code (two characters) of the marketing (selling) airline.
flight.legs[].segments[]. operatingAirlineCode string Yes IATA code (two characters) of the operating (owning the aircraft) airline.
flight.legs[].segments[]. deptCode string Yes IATA code (three letters) of the departure airport.
flight.legs[].segments[]. destCode string Yes IATA code (three letters) of the destination airport.
flight.legs[].segments[]. deptDate string Yes Date in ISO-8601 format e.g. MM/DD/YYYY, YYYY-MM-DD or YYYY-MM-DDThh:mm:ss. Time is not required.
flight.legs[].segments[]. fareCode string Yes Single letter code also known as booking code or Reservation Booking Designator (RBD).
flight.legs[].segments[]. flightNumber string Yes Flight number without airline code prefix. In other words just digits e.g. 3861.
flight.legs[].segments[]. distance integer No Flown distance in land miles rounded to whole mile. If absent, the shortest distance between two airports will be calculated instead. Recommended to ensure best accuracy.
flight. price object No Required to ensure correct calculations for revenue-based frequent flyer programs. Strongly recommended.
flight.price. currencyCode string Yes ISO-4217 3-letter currency code
flight.price. total double Yes Total fare price for entire flight including taxes, fees, surcharges etc.
flight.price. fare double No Base fare price. Recommended to ensure best accuracy for revenue-based frequent flyer programs.
flight.price. taxes double No Total amount for all taxes.
flight.price. surcharges double No Total amount of surcharges imposed by the carrier.
programs[] array No Collection of frequent flyer program objects for which you want to calculate upgrades eligibility. Used to personalize results based on user memberships.
programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs. You can request list of programs with their codes using Programs method.
programs[]. tierCode integer No Code of status tier for specified frequent flyer program as in Appendix: Status tiers. Used to personalize calculations for users holding special status tier in a program e.g. Silver Status. If not specified, default, basic status tier will be used.
applyAllPrograms boolean No If set true and programs[] array is absent or empty, then all applicable combinations of frequent flyer program and its status tiers will be returned (not only pair of default program and basic status tier as in CalculateUpgrades method).
clientUserId string No Unique user id to link subsequent requests to the same person. Strongly recommended.

Response structure

Sample response

{
  "Success": true,
  "Status": {
    "Code": 0,
    "Message": "OK"
  },
  "Value": {
    "uniqueId": "56cbd707-66de-4b94-a132-4a7650ed3c67",
    "flights": [{
      "flightId": "SK1674-SK0503",
      "programs": [{
        "programCode": "AKF",
        "tierCode": 1,
        "options": [{
            "targetFareType": 48,
            "totalCost": 10000,
            "details": [{
                "targetId": "SK1674-SK0503",
                "legLevel": true,
                "cost": 10000
            }]
        }]
      },{
          "programCode": "AKF",
          "tierCode": 8,
          "options": [{
            "targetFareType": 48,
            "totalCost": 8000,
            "details": [{
                "targetId": "SK1674-SK0503",
                "legLevel": true,
                "cost": 8000
            }]
          }]
      }]
    }],
    "programs": [{
      "programCode": "AKF"
    }],
    "errors": []
  }
}

Property Value Required Description
Success boolean Yes True if request has been executed successfully
Status object Yes Contains status of executed method
Status. Code integer Yes Response status code as in Appendix: Status codes.
Status. Message string Yes Human-readable message describing response status.
Value object No Contains cabin upgrade options for each specified flight and combinations of frequent flyer program and status tier pairs (if set in request). May be absent in case of error.
Value. uniqueId string Yes Unique id generated for every request.
Value. flights[] array Yes Collection of flights containing frequent flyer earnings.
Value.flights[]. flightId string Yes Unique id of the flight specified in request.
Value.flights[]. programs[] array No Collection of objects with cabin upgrade options for particular frequent flyer program and its certain status tier. It reflects fact, that one flight leg or segment can potentially be upgraded with redeemable miles from different programs.
Value.flights[].programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value.flights[].programs[]. tierCode integer Yes Code of status tier for specified frequent flyer program as in Appendix: Status tiers. By default only basic status tier is returned.
Value.flights[].programs[]. options[] array Yes Collection of cabin upgrade options e.g. upgrade to Economy is one option, upgrade to Business is another.
Value.flights[].programs[].options[]. targetFareType integer Yes Code of target fare type (cabin) as listed in Appendix: Fare families.
Value.flights[].programs[].options[]. totalCost integer Yes Cost of entire upgrade option in redeemable miles used in particular frequent flyer program.
Value.flights[].programs[].options[]. details[] array Yes Collection of upgrade objects for particular, eligible flight leg and/or segment.
Value.flights[].programs[].options[].details[]. targetId string Yes Unique id of flight leg or segment specified in request (or generated if absent). Indicates which fragment of entire flight is eligible for an upgrade.
Value.flights[].programs[].options[].details[]. legLevel boolean Yes True if targetId field relates to flight leg. False if it relates to flight segment.
Value.flights[].programs[].options[].details[]. cost integer Yes Cost of single leg or segment upgrade in redeemable miles used in particular frequent flyer program.
Value. programs[] array Yes Collection of basic information about frequent flyer programs used in response. For more detailed information and full list of programs, you need to use Programs method. Array may be empty if there were no upgrade options available for any of specified flights.
Value.programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value. errors[] array Yes Collection of error objects for specific flights (if any occured).
Value.errors[]. flightId string Yes Unique id of the flight specified in request.
Value.errors[]. code string Yes Error code indicating problem encountered when processing flight information in request. See all error codes listed in Appendix: Error codes.
Value.errors[]. message string Yes Human-readable message for debugging purposes.

Benefits

The Benefits method returns all supported frequent flyer benefit types such as lounge access or priority check-in (see full list in Attachment: Benefit types).

You can use returned information in combination with any method, that calculates frequent flyer benefits such as CalculateBenefits.

HTTP Request

GET /api/benefits

Request parameters

This method has no parameters.

Response structure

Sample response

{
    "Success": true,
    "Status": {
        "Code": 0,
        "Message": "OK"
    },
    "Value": [{
        "code": "CMPCHG",
        "name": "Complimentary Flight Change",
        "description": "No charge for members to change to an earlier or later flight"
    }, {
        "code": "CMPSTG",
        "name": "Complimentary Seating"
    }, {
        "code": "LNGACS",
        "name": "Lounge Access"
    }, {
        "code": "PRMBRG",
        "name": "Premium Beverage"
    }, {
        "code": "PTYBDG",
        "name": "Priority Boarding"
    }, {
        "code": "PTYBDO",
        "name": "Priority Baggage Handling"
    }, {
        "code": "PTYCHK",
        "name": "Priority Check-In"
    }, {
        "code": "PTYDSK",
        "name": "Priority at Transfer Desks"
    }, {
        "code": "PTYSTY",
        "name": "Priority At Immigration or Security"
    }, {
        "code": "XTRBGG",
        "name": "Extra Baggage Allowance"
    }, {
        "code": "XTRLRM",
        "name": "Extra Legroom"
    }]
}

Property Value Required Description
Success boolean Yes True if request has been executed successfully
Status object Yes Contains status of executed method
Status. Code integer Yes Response status code as in Appendix: Status codes.
Status. Message string Yes Human-readable message describing response status.
Value[] array No Contains list of frequent flyer benefit types. May be absent in case of error.
Value[]. code string Yes Benefit type code, that you can find in Appendix: Benefit types. You can provide translations of benefit type name and description based on this code.
Value[]. name string Yes General name of benefit type in English.
Value[]. description string No Description of benefit type in English intended for end-user interface.

CalculateBenefits

Sample request

{
  "flights": [{
    "flightId": "SK1674-SK0503|SK0502-SK0679",
    "price": {
      "currencyCode": "USD",
      "total": 150.0,
      "fare": 128.5,
      "surcharges": 11.5,
      "taxes": 10
    },
    "legs":[{
      "legId": "SK1674-SK0503",
      "segments": [{
        "segmentId": "SK1674",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "TXL",
        "destCode": "CPH",
        "deptDate": "2016-07-02T09:35:00",
        "fareCode": "A",
        "flightNumber": 1674,
        "distance": 213
      },{
        "segmentId": "SK0503",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "CPH",
        "destCode": "LHR",
        "deptDate": "2016-07-02T12:05:00",
        "fareCode": "A",
        "flightNumber": 503,
        "distance":610
      }]
    },{
      "legId": "SK0502-SK0679",
      "segments": [{
        "segmentId": "SK0502",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "LHR",
        "destCode": "CPH",
        "deptDate": "2016-07-16T09:50:00",
        "fareCode": "A",
        "flightNumber": 502,
        "distance": 610
      },{
        "segmentId": "SK0679",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "CPH",
        "destCode": "TXL",
        "deptDate": "2016-07-16T15:05:00",
        "fareCode": "A",
        "flightNumber": 679,
        "distance": 213
      }]
    }]
  }],
  "programs": [{
    "programCode": "AMM",
    "tierCode": 8
  }],
  "clientUserId": "0000001internal"
}

The CalculateBenefits method returns the eligible frequent flyer benefits for every flight in a request.

HTTP Request

POST /api/benefits/calculate

Request parameters

Should be sent as the body of a request in JSON format.

Property Value Required Description
flights[] array Yes Collection of flights for which frequent flyer benefits will be calculated.
flights[]. flightId string Yes Unique id of the flight used as a reference in API response.
flights[]. legs[] array Yes Collection of flight legs. Flight leg may contain a few flight segments separated by layovers. Round-trip flight consists of two flight legs.
flights[].legs[]. legId string No Unique id of the flight leg used as a reference in API response. Will be generated if absent.
flights[].legs[]. segments[] array Yes Collection of flight segments. Flight segment is characterized by single takeoff and landing.
flights[].legs[].segments[]. segmentId string No Unique id of the flight segment used as a reference in API response. Will be generated if absent.
flights[].legs[].segments[]. marketingAirlineCode string Yes IATA code (two characters) of the marketing (selling) airline.
flights[].legs[].segments[]. operatingAirlineCode string Yes IATA code (two characters) of the operating (owning the aircraft) airline.
flights[].legs[].segments[]. deptCode string Yes IATA code (three letters) of the departure airport.
flights[].legs[].segments[]. destCode string Yes IATA code (three letters) of the destination airport.
flights[].legs[].segments[]. deptDate string Yes Date in ISO-8601 format e.g. MM/DD/YYYY, YYYY-MM-DD or YYYY-MM-DDThh:mm:ss. Time is not required.
flights[].legs[].segments[]. fareCode string Yes Single letter code also known as booking code or Reservation Booking Designator (RBD).
flights[].legs[].segments[]. flightNumber string Yes Flight number without airline code prefix. In other words just digits e.g. 3861.
flights[].legs[].segments[]. distance integer No Flown distance in land miles rounded to whole mile. If absent, the shortest distance between two airports will be calculated instead. Recommended to ensure best accuracy.
flights[]. price object No Required to ensure correct calculations for revenue-based frequent flyer programs. Strongly recommended.
flights[].price. currencyCode string Yes ISO-4217 3-letter currency code
flights[].price. total double Yes Total fare price for entire flight including taxes, fees, surcharges etc.
flights[].price. fare double No Base fare price. Recommended to ensure best accuracy for revenue-based frequent flyer programs.
flights[].price. taxes double No Total amount for all taxes.
flights[].price. surcharges double No Total amount of surcharges imposed by the carrier.
programs[] array No Collection of frequent flyer program objects for which you want to calculate frequent flyer benefits. Used to personalize results based on user memberships.
programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs. You can request list of programs with their codes using Programs method.
programs[]. tierCode integer No Code of status tier for specified frequent flyer program as in Appendix: Status tiers. Used to personalize calculations for users holding special status tier in a program e.g. Silver Status. If not specified, default, basic status tier will be used.
clientUserId string No Unique user id to link subsequent requests to the same person. Strongly recommended.

Response structure

Sample response

{
  "Success": true,
  "Status": {
    "Code": 0,
    "Message": "OK"
  },
  "Value": {
    "uniqueId": "56cbd707-66de-4b94-a132-4a7650ed3c67",
    "flights": [{
      "flightId": "SK1674-SK0503|SK0502-SK0679",
      "programs": [{
        "programCode": "AMM",
        "tierCode": 8,
        "benefits": [{
            "targetId": "SK1674",
            "legLevel": false,
            "code": "PTYCHK",
            "options": [{
                "name": "Easier check-in process",
                "disclaimer": [
                    "In addition to Alitalia's digital services, Tele Check-in, check-in at Business desks even with an Economy ticket."
                ],
                "guests": 0
            }]
        },{
            "targetId": "SK0502-SK0679",
            "legLevel": true,
            "code": "XTRBGG",
            "options": [{
                "name": "One free extra bag",
                "disclaimer": [
                    "Free transportation and priority baggage claim for sports equipment or a surf board up to 250cm long"
                ],
                "guests": 1,
                "weightMetricType": "kg",
                "weight": 23,
                "quantity": 1
            }]
        },{
            "targetId": "SK0502",
            "legLevel": false,
            "code": "LNGACS",
            "options": [{
                "name": "Alitalia Lounges",
                "disclaimer": [
                    "Free of charge for children up to 2 years of age."
                ],
                "guests": 1
            }]
        }]
      }]
    }],
    "programs": [{
      "programCode": "AMM"
    }],
    "errors": []
  }
}

Property Value Required Description
Success boolean Yes True if request has been executed successfully
Status object Yes Contains status of executed method
Status. Code integer Yes Response status code as in Appendix: Status codes.
Status. Message string Yes Human-readable message describing response status.
Value object No Contains frequent flyer benefits for each specified flight and combinations of frequent flyer program and status tier pairs (if set in request). May be absent in case of error.
Value. uniqueId string Yes Unique id generated for every request.
Value. flights[] array Yes Collection of flights containing frequent flyer benefits.
Value.flights[]. flightId string Yes Unique id of the flight specified in request.
Value.flights[]. programs[] array No Collection of objects with benefits for particular frequent flyer program and its certain status tier. It reflects fact, that one flight leg or segment can potentially include benefits from different programs.
Value.flights[].programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value.flights[].programs[]. tierCode integer Yes Code of status tier for specified frequent flyer program as in Appendix: Status tiers. By default only basic status tier is returned.
Value.flights[].programs[]. benefits[] array Yes Collection of frequent flyer benefits groupped by benefit type (Appendix: Benefit types).
Value.flights[].programs[].benefits[]. targetId string Yes Unique id of flight leg or segment specified in request (or generated if absent). Indicates which fragment of entire flight has particular benefit type.
Value.flights[].programs[].benefits[]. legLevel boolean Yes True if targetId field relates to flight leg. False if it relates to flight segment.
Value.flights[].programs[].benefits[]. code string Yes Benefit type code as in Appendix: Benefit types.
Value.flights[].programs[].benefits[]. options[] array Yes Eligible benefits for particular benefit type and particular flight fragment (segment or leg). In majority of cases there is only one benefit available. There might be more options e.g. when passenger is eligible to access two different lounges on one airport.
Value.flights[].programs[].benefits[].options[]. name string Yes Name specific for particular frequent flyer program e.g. OneWorld S7 Lounge Access. If you need more generic name, use benefit type name provided in Benefits method.
Value.flights[].programs[].benefits[].options[]. disclaimer[] array No Array of strings with special conditions or restrictions for the benefit. In English.
Value.flights[].programs[].benefits[].options[]. guests integer Yes Maximum number of guests travelling with member eligible for particular benefit.
Value.flights[].programs[].benefits[].options[]. quantity integer No Number of extra pieces of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. weightMetricType string No Weight unit used for baggage restrictions (kg or lb). Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. weight integer No Maximum weight of one extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. totalWeight integer No Total maximum weight of all pieces of extra baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. sizeMetricType string No Length unit used for baggage restrictions (cm or in). Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. sizeWidth integer No Maximum width of extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. sizeLength integer No Maximum length of extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. sizeHeight integer No Maximum height of extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. totalLength integer No Maximum sum of dimensions of every piece of extra baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value. programs[] array Yes Collection of basic information about frequent flyer programs used in response. For more detailed information and full list of programs, you need to use Programs method. Array may be empty if there were no eligible benefits on any of specified flights.
Value.programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value. errors[] array Yes Collection of error objects for specific flights (if any occured).
Value.errors[]. flightId string Yes Unique id of the flight specified in request.
Value.errors[]. code string Yes Error code indicating problem encountered when processing flight information in request. See all error codes listed in Appendix: Error codes.
Value.errors[]. message string Yes Human-readable message for debugging purposes.

CalculateOneBenefits

Sample request

{
  "flight": {
    "flightId": "SK1674-SK0503|SK0502-SK0679",
    "price": {
      "currencyCode": "USD",
      "total": 150.0,
      "fare": 128.5,
      "surcharges": 11.5,
      "taxes": 10
    },
    "legs":[{
      "legId": "SK1674-SK0503",
      "segments": [{
        "segmentId": "SK1674",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "TXL",
        "destCode": "CPH",
        "deptDate": "2016-07-02T09:35:00",
        "fareCode": "A",
        "flightNumber": 1674,
        "distance": 213
      },{
        "segmentId": "SK0503",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "CPH",
        "destCode": "LHR",
        "deptDate": "2016-07-02T12:05:00",
        "fareCode": "A",
        "flightNumber": 503,
        "distance":610
      }]
    },{
      "legId": "SK0502-SK0679",
      "segments": [{
        "segmentId": "SK0502",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "LHR",
        "destCode": "CPH",
        "deptDate": "2016-07-16T09:50:00",
        "fareCode": "A",
        "flightNumber": 502,
        "distance": 610
      },{
        "segmentId": "SK0679",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "CPH",
        "destCode": "TXL",
        "deptDate": "2016-07-16T15:05:00",
        "fareCode": "A",
        "flightNumber": 679,
        "distance": 213
      }]
    }]
  },
  "programs": [{
    "programCode": "AMM",
    "tierCode": 8
  }],
  "clientUserId": "0000001internal"
}

The CalculateOneBenefits method returns the eligible frequent flyer benefits for a single flight.

In contrast to the CalculateBenefits method, you can return benefits for all applicable frequent flyer programs and their status tier by setting applyAllPrograms flag as true.

HTTP Request

POST /api/benefits/calculateone

Request parameters

Should be sent as the body of a request in JSON format.

Property Value Required Description
flight object Yes Flight for which frequent flyer benefits will be calculated.
flight. flightId string Yes Unique id of the flight used as a reference in API response.
flight. legs[] array Yes Collection of flight legs. Flight leg may contain a few flight segments separated by layovers. Round-trip flight consists of two flight legs.
flight.legs[]. legId string No Unique id of the flight leg used as a reference in API response. Will be generated if absent.
flight.legs[]. segments[] array Yes Collection of flight segments. Flight segment is characterized by single takeoff and landing.
flight.legs[].segments[]. segmentId string No Unique id of the flight segment used as a reference in API response. Will be generated if absent.
flight.legs[].segments[]. marketingAirlineCode string Yes IATA code (two characters) of the marketing (selling) airline.
flight.legs[].segments[]. operatingAirlineCode string Yes IATA code (two characters) of the operating (owning the aircraft) airline.
flight.legs[].segments[]. deptCode string Yes IATA code (three letters) of the departure airport.
flight.legs[].segments[]. destCode string Yes IATA code (three letters) of the destination airport.
flight.legs[].segments[]. deptDate string Yes Date in ISO-8601 format e.g. MM/DD/YYYY, YYYY-MM-DD or YYYY-MM-DDThh:mm:ss. Time is not required.
flight.legs[].segments[]. fareCode string Yes Single letter code also known as booking code or Reservation Booking Designator (RBD).
flight.legs[].segments[]. flightNumber string Yes Flight number without airline code prefix. In other words just digits e.g. 3861.
flight.legs[].segments[]. distance integer No Flown distance in land miles rounded to whole mile. If absent, the shortest distance between two airports will be calculated instead. Recommended to ensure best accuracy.
flight. price object No Required to ensure correct calculations for revenue-based frequent flyer programs. Strongly recommended.
flight.price. currencyCode string Yes ISO-4217 3-letter currency code
flight.price. total double Yes Total fare price for entire flight including taxes, fees, surcharges etc.
flight.price. fare double No Base fare price. Recommended to ensure best accuracy for revenue-based frequent flyer programs.
flight.price. taxes double No Total amount for all taxes.
flight.price. surcharges double No Total amount of surcharges imposed by the carrier.
programs[] array No Collection of frequent flyer program objects for which you want to calculate frequent flyer benefits. Used to personalize results based on user memberships.
programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs. You can request list of programs with their codes using Programs method.
programs[]. tierCode integer No Code of status tier for specified frequent flyer program as in Appendix: Status tiers. Used to personalize calculations for users holding special status tier in a program e.g. Silver Status. If not specified, default, basic status tier will be used.
applyAllPrograms boolean No If set true and programs[] array is absent or empty, then all applicable combinations of frequent flyer program and its status tiers will be returned (not only pair of default program and basic status tier as in CalculateBenefits method).
clientUserId string No Unique user id to link subsequent requests to the same person. Strongly recommended.

Response structure

Sample response

{
  "Success": true,
  "Status": {
    "Code": 0,
    "Message": "OK"
  },
  "Value": {
    "uniqueId": "56cbd707-66de-4b94-a132-4a7650ed3c67",
    "flights": [{
      "flightId": "SK1674-SK0503|SK0502-SK0679",
      "programs": [{
        "programCode": "AMM",
        "tierCode": 8,
        "benefits": [{
            "targetId": "SK1674",
            "legLevel": false,
            "code": "PTYCHK",
            "options": [{
                "name": "Easier check-in process",
                "disclaimer": [
                    "In addition to Alitalia's digital services, Tele Check-in, check-in at Business desks even with an Economy ticket."
                ],
                "guests": 0
            }]
        },{
            "targetId": "SK0502-SK0679",
            "legLevel": true,
            "code": "XTRBGG",
            "options": [{
                "name": "One free extra bag",
                "disclaimer": [
                    "Free transportation and priority baggage claim for sports equipment or a surf board up to 250cm long"
                ],
                "guests": 1,
                "weightMetricType": "kg",
                "weight": 23,
                "quantity": 1
            }]
        },{
            "targetId": "SK0502",
            "legLevel": false,
            "code": "LNGACS",
            "options": [{
                "name": "Alitalia Lounges",
                "disclaimer": [
                    "Free of charge for children up to 2 years of age."
                ],
                "guests": 1
            }]
        }]
      }]
    }],
    "programs": [{
      "programCode": "AMM"
    }],
    "errors": []
  }
}

Property Value Required Description
Success boolean Yes True if request has been executed successfully
Status object Yes Contains status of executed method
Status. Code integer Yes Response status code as in Appendix: Status codes.
Status. Message string Yes Human-readable message describing response status.
Value object No Contains frequent flyer benefits for each specified flight and combinations of frequent flyer program and status tier pairs (if set in request). May be absent in case of error.
Value. uniqueId string Yes Unique id generated for every request.
Value. flights[] array Yes Collection of flights containing frequent flyer benefits.
Value.flights[]. flightId string Yes Unique id of the flight specified in request.
Value.flights[]. programs[] array No Collection of objects with benefits for particular frequent flyer program and its certain status tier. It reflects fact, that one flight leg or segment can potentially include benefits from different programs.
Value.flights[].programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value.flights[].programs[]. tierCode integer Yes Code of status tier for specified frequent flyer program as in Appendix: Status tiers. By default only basic status tier is returned.
Value.flights[].programs[]. benefits[] array Yes Collection of frequent flyer benefits groupped by benefit type (Appendix: Benefit types).
Value.flights[].programs[].benefits[]. targetId string Yes Unique id of flight leg or segment specified in request (or generated if absent). Indicates which fragment of entire flight has particular benefit type.
Value.flights[].programs[].benefits[]. legLevel boolean Yes True if targetId field relates to flight leg. False if it relates to flight segment.
Value.flights[].programs[].benefits[]. code string Yes Benefit type code as in Appendix: Benefit types.
Value.flights[].programs[].benefits[]. options[] array Yes Eligible benefits for particular benefit type and particular flight fragment (segment or leg). In majority of cases there is only one benefit available. There might be more options e.g. when passenger is eligible to access two different lounges on one airport.
Value.flights[].programs[].benefits[].options[]. name string Yes Name specific for particular frequent flyer program e.g. OneWorld S7 Lounge Access. If you need more generic name, use benefit type name provided in Benefits method.
Value.flights[].programs[].benefits[].options[]. disclaimer[] array No Array of strings with special conditions or restrictions for the benefit. In English.
Value.flights[].programs[].benefits[].options[]. guests integer Yes Maximum number of guests travelling with member eligible for particular benefit.
Value.flights[].programs[].benefits[].options[]. quantity integer No Number of extra pieces of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. weightMetricType string No Weight unit used for baggage restrictions (kg or lb). Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. weight integer No Maximum weight of one extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. totalWeight integer No Total maximum weight of all pieces of extra baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. sizeMetricType string No Length unit used for baggage restrictions (cm or in). Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. sizeWidth integer No Maximum width of extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. sizeLength integer No Maximum length of extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. sizeHeight integer No Maximum height of extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits[].options[]. totalLength integer No Maximum sum of dimensions of every piece of extra baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value. programs[] array Yes Collection of basic information about frequent flyer programs used in response. For more detailed information and full list of programs, you need to use Programs method. Array may be empty if there were no eligible benefits on any of specified flights.
Value.programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value. errors[] array Yes Collection of error objects for specific flights (if any occured).
Value.errors[]. flightId string Yes Unique id of the flight specified in request.
Value.errors[]. code string Yes Error code indicating problem encountered when processing flight information in request. See all error codes listed in Appendix: Error codes.
Value.errors[]. message string Yes Human-readable message for debugging purposes.

CalculateMixed

Sample request

{
  "calculateEarnings": true,
  "calculateUpgrades": true,
  "calculateBenefits": true,
  "flights": [{
    "flightId": "SK1674-SK0503",
    "price": {
      "currencyCode": "USD",
      "total": 150.0,
      "fare": 128.5,
      "surcharges": 11.5,
      "taxes": 10
    },
    "legs":[{
      "legId": "SK1674-SK0503",
      "segments": [{
        "segmentId": "SK1674",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "TXL",
        "destCode": "CPH",
        "deptDate": "2016-07-02T09:35:00",
        "fareCode": "A",
        "flightNumber": 1674,
        "distance": 213
      },{
        "segmentId": "SK0503",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "CPH",
        "destCode": "LHR",
        "deptDate": "2016-07-02T12:05:00",
        "fareCode": "A",
        "flightNumber": 503,
        "distance":610
      }]
    }]
  }],
  "clientUserId": "0000001internal"
}

The CalculateMixed method is a shorthand method that returns a subset of features, selectable between the frequent flyer earnings (miles), cabin upgrades and status benefits of all flights in a request.

You can specify frequent flyer programs to personalize the calculations in the response based on a user’s program memberships. If you don’t specify, the information will be calculated and returned according to the frequent flyer program of the marketing carrier of each flight. For example if marketing carrier is Delta, frequent flyer information will be returned for Delta SkyMiles program.

See CalculateMiles, CalculateUpgrades and CalculateBenefits methods, which can be used separatelly for requesting the same information.

HTTP Request

POST /api/mixed/calculate

Request parameters

Should be sent as the body of a request in JSON format.

Property Value Required Description
calculateEarnings boolean No True to calculate frequent flyer earnings (miles) for specified flights. Default: false. See CalculateMiles method.
calculateUpgrades boolean No True to calculate upgrade eligibility for specified flights. Default: false. See CalculateUpgrades method.
calculateBenefits boolean No True to calculate frequent flyer benefits for specified flights. Default: false. See CalculateBenefits method.
flights[] array Yes Collection of flights for which frequent flyer information will be calculated.
flights[]. flightId string Yes Unique id of the flight used as a reference in API response
flights[]. legs[] array Yes Collection of flight legs. Flight leg may contain a few flight segments separated by layovers. Round-trip flight consists of two flight legs.
flights[].legs[]. legId string No Unique id of the flight leg used as a reference in API response. Will be generated if absent.
flights[].legs[]. segments[] array Yes Collection of flight segments. Flight segment is characterized by single takeoff and landing.
flights[].legs[].segments[]. segmentId string No Unique id of the flight segment used as a reference in API response. Will be generated if absent.
flights[].legs[].segments[]. marketingAirlineCode string Yes IATA code (two characters) of the marketing (selling) airline.
flights[].legs[].segments[]. operatingAirlineCode string Yes IATA code (two characters) of the operating (owning the aircraft) airline.
flights[].legs[].segments[]. deptCode string Yes IATA code (three letters) of the departure airport.
flights[].legs[].segments[]. destCode string Yes IATA code (three letters) of the destination airport.
flights[].legs[].segments[]. deptDate string Yes Date in ISO-8601 format e.g. MM/DD/YYYY, YYYY-MM-DD or YYYY-MM-DDThh:mm:ss. Time is not required.
flights[].legs[].segments[]. fareCode string Yes Single letter code also known as booking code or Reservation Booking Designator (RBD).
flights[].legs[].segments[]. flightNumber string Yes Flight number without airline code prefix. In other words just digits e.g. 3861.
flights[].legs[].segments[]. distance integer No Flown distance in land miles rounded to whole mile. If absent, the shortest distance between two airports will be calculated instead. Recommended to ensure best accuracy.
flights[]. price object No Required to ensure correct calculations for revenue-based frequent flyer programs. Strongly recommended.
flights[].price. currencyCode string Yes ISO-4217 3-letter currency code
flights[].price. total double Yes Total fare price for entire flight including taxes, fees, surcharges etc.
flights[].price. fare double No Base fare price. Recommended to ensure best accuracy for revenue-based frequent flyer programs.
flights[].price. taxes double No Total amount for all taxes.
flights[].price. surcharges double No Total amount of surcharges imposed by the carrier.
programs[] array No Collection of frequent flyer program objects for which you want to calculate miles. Used to personalize results based on user memberships.
programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs. You can request list of programs with their codes using Programs method.
programs[]. tierCode integer No Code of status tier for specified frequent flyer program as in Appendix: Status tiers. Used to personalize calculations for users holding special status tier in a program e.g. Silver Status. If not specified, default, basic status tier will be used.
clientUserId string No Unique user id to link subsequent requests to the same person. Strongly recommended.

Response structure

Sample response

{
  "Success": true,
  "Status": {
    "Code": 0,
    "Message": "OK"
  },
  "Value": {
    "uniqueId": "56cbd707-66de-4b94-a132-4a7650ed3c67",
    "flights": [{
      "flightId": "SK1674-SK0503",
      "programs": [{
        "programCode": "SEB",
        "tierCode": 1,
        "earnings": {
          "earnings": [{
            "metricCode": 1,
            "value": 5250
          },{
            "metricCode": 2,
            "value": 5250
          },{
            "metricCode": 3,
            "value": 2
          }]
        },
        "upgrades": {
          "options": [{
            "targetFareType": 48,
            "details": [{
              "targetId": "SK1674-SK0503",
              "legLevel": true
            }]
          }]
        },
        "benefits": {
          "benefits": [{
            "targetId": "SK1674",
            "legLevel": false,
            "code": "XTRLRM",
            "options": [{
              "name": "Extended Seat Plus",
              "guests": 0
            }]
          },{
            "targetId": "SK0503",
            "legLevel": false,
            "code": "XTRLRM",
            "options": [{
              "name": "Extended Seat Plus",
              "guests": 0
            }]
          },{
            "targetId": "SK1674",
            "legLevel": false,
            "code": "PFDSTG",
            "options": [{
              "name": "Premium Front Cabin Seat",
              "guests": 0
            },{
              "name": "Premium Duo Seat on A380 Upper Deck",
              "guests": 0
            }]
          }]
        }
      }]
    }],
    "programs": [{
      "programCode": "SEB"
    }],
    "errors": []
  }
}

Property Value Required Description
Success boolean Yes True if request has been executed successfully
Status object Yes Contains status of executed method
Status. Code integer Yes Response status code as in Appendix: Status codes.
Status. Message string Yes Human-readable message describing response status.
Value object No Contains frequent flyer information for specified (or default) pairs of frequent flyer program and status tier. May be absent in case of error.
Value. uniqueId string Yes Unique id generated for every request.
Value. flights[] array Yes Collection of flights containing frequent flyer information.
Value.flights[]. flightId string Yes Unique id of the flight specified in request.
Value.flights[]. programs[] array No Collection of objects with frequent flyer information for particular frequent flyer program and its certain status tier.
Value.flights[].programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value.flights[].programs[]. tierCode integer Yes Code of status tier for specified frequent flyer program as in Appendix: Status tiers. By default only basic status tier is returned.
Value.flights[].programs[]. earnings object No Object containing frequent flyer earnings (miles). Absent if calculateEarnings flag in request is false or not set.
Value.flights[].programs[].earnings. earnings[] array Yes Collection of objects with frequent flyer earnings (miles). Each object contains earnings for different accrual (type of earned miles).
Value.flights[].programs[].earnings.earnings[]. metricCode integer Yes Code of accrual (type of earned miles) as listed in Appendix: Accrual types.
Value.flights[].programs[].earnings.earnings[]. value double Yes Number of earned frequent flyer miles or points. In some cases it may be a decimal.
Value.flights[].programs[]. upgrades object No Object containing eligibility of cabin upgrades. Absent if calculateUpgrades flag in request is false or not set.
Value.flights[].programs[].upgrades. options[] array Yes Collection of cabin upgrade options e.g. upgrade to Economy is one option, upgrade to Business is another.
Value.flights[].programs[].upgrades.options[]. targetFareType integer Yes Code of target fare type (cabin) as listed in Appendix: Fare families.
Value.flights[].programs[].upgrades.options[]. details[] array Yes Collection of upgrade objects for particular, eligible flight leg and/or segment.
Value.flights[].programs[].upgrades.options[].details[]. targetId string Yes Unique id of flight leg or segment specified in request (or generated if absent). Indicates which fragment of entire flight is eligible for an upgrade.
Value.flights[].programs[].upgrades.options[].details[]. legLevel boolean Yes True if targetId field relates to flight leg. False if it relates to flight segment.
Value.flights[].programs[]. benefits object No Object containing frequent flyer benefits. Absent if calculateBenefits flag in request is false or not set.
Value.flights[].programs[].benefits. benefits[] array Yes Collection of frequent flyer benefits groupped by benefit type (Appendix: Benefit types).
Value.flights[].programs[].benefits.benefits[]. targetId string Yes Unique id of flight leg or segment specified in request (or generated if absent). Indicates which fragment of entire flight has particular benefit type.
Value.flights[].programs[].benefits.benefits[]. legLevel boolean Yes True if targetId field relates to flight leg. False if it relates to flight segment.
Value.flights[].programs[].benefits.benefits[]. code string Yes Benefit type code as in Appendix: Benefit types.
Value.flights[].programs[].benefits.benefits[]. options[] array Yes Eligible benefits for particular benefit type and particular flight fragment (segment or leg). In majority of cases there is only one benefit available. There might be more options e.g. when passenger is eligible to access two different lounges on one airport.
Value.flights[].programs[].benefits.benefits[].options[]. name string Yes Name specific for particular frequent flyer program e.g. OneWorld S7 Lounge Access. If you need more generic name, use benefit type name provided in Benefits method.
Value.flights[].programs[].benefits.benefits[].options[]. disclaimer[] array No Array of strings with special conditions or restrictions for the benefit. In English.
Value.flights[].programs[].benefits.benefits[].options[]. guests integer Yes Maximum number of guests travelling with member eligible for particular benefit.
Value.flights[].programs[].benefits.benefits[].options[]. quantity integer No Number of extra pieces of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. weightMetricType string No Weight unit used for baggage restrictions (kg or lb). Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. weight integer No Maximum weight of one extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. totalWeight integer No Total maximum weight of all pieces of extra baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. sizeMetricType string No Length unit used for baggage restrictions (cm or in). Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. sizeWidth integer No Maximum width of extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. sizeLength integer No Maximum length of extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. sizeHeight integer No Maximum height of extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. totalLength integer No Maximum sum of dimensions of every piece of extra baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value. programs[] array Yes Collection of basic information about frequent flyer programs used in response. For more detailed information and full list of programs, you need to use Programs method. Array may be empty if there were no programs earning to any of specified flights.
Value.programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value. errors[] array Yes Collection of error objects for specific flights (if any occured).
Value.errors[]. flightId string Yes Unique id of the flight specified in request.
Value.errors[]. code string Yes Error code indicating problem encountered when processing flight information in request. See all error codes listed in Appendix: Error codes.
Value.errors[]. message string Yes Human-readable message for debugging purposes.

CalculateOneMixed

Sample request

{
  "applyAllPrograms": true,
  "calculateEarnings": true,
  "calculateUpgrades": true,
  "calculateBenefits": false,
  "flight": {
    "flightId": "SK1674-SK0503",
    "price": {
      "currencyCode": "USD",
      "total": 150.0,
      "fare": 128.5,
      "surcharges": 11.5,
      "taxes": 10
    },
    "legs":[{
      "legId": "SK1674-SK0503",
      "segments": [{
        "segmentId": "SK1674",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "TXL",
        "destCode": "CPH",
        "deptDate": "2016-07-02T09:35:00",
        "fareCode": "A",
        "flightNumber": 1674,
        "distance": 213
      },{
        "segmentId": "SK0503",
        "marketingAirlineCode": "SK",
        "operatingAirlineCode": "SK",
        "deptCode": "CPH",
        "destCode": "LHR",
        "deptDate": "2016-07-02T12:05:00",
        "fareCode": "A",
        "flightNumber": 503,
        "distance":610
      }]
    }]
  },
  "clientUserId": "0000001internal"
}

The CalculateOneMixed method is a shorthand method that returns a subset of features, selectable between the frequent flyer earnings (miles), cabin upgrades and status benefits of a single flight.

In contrast to the CalculateMixed method, you can return information for all applicable frequent flyer programs and their status tiers by setting applyAllPrograms flag as true.

HTTP Request

POST /api/mixed/calculateone

Request parameters

Should be sent as the body of a request in JSON format.

Property Value Required Description
calculateEarnings boolean No True to calculate frequent flyer earnings (miles) for specified flight. Default: false. See CalculateOneMiles method.
calculateUpgrades boolean No True to calculate upgrade eligibility for specified flight. Default: false. See CalculateOneUpgrades method.
calculateBenefits boolean No True to calculate frequent flyer benefits for specified flight. Default: false. See CalculateOneBenefits method.
flight object Yes Flight for which frequent flyer information will be calculated.
flight. flightId string Yes Unique id of the flight used as a reference in API response
flight. legs[] array Yes Collection of flight legs. Flight leg may contain a few flight segments separated by layovers. Round-trip flight consists of two flight legs.
flight.legs[]. legId string No Unique id of the flight leg used as a reference in API response. Will be generated if absent.
flight.legs[]. segments[] array Yes Collection of flight segments. Flight segment is characterized by single takeoff and landing.
flight.legs[].segments[]. segmentId string No Unique id of the flight segment used as a reference in API response. Will be generated if absent.
flight.legs[].segments[]. marketingAirlineCode string Yes IATA code (two characters) of the marketing (selling) airline.
flight.legs[].segments[]. operatingAirlineCode string Yes IATA code (two characters) of the operating (owning the aircraft) airline.
flight.legs[].segments[]. deptCode string Yes IATA code (three letters) of the departure airport.
flight.legs[].segments[]. destCode string Yes IATA code (three letters) of the destination airport.
flight.legs[].segments[]. deptDate string Yes Date in ISO-8601 format e.g. MM/DD/YYYY, YYYY-MM-DD or YYYY-MM-DDThh:mm:ss. Time is not required.
flight.legs[].segments[]. fareCode string Yes Single letter code also known as booking code or Reservation Booking Designator (RBD).
flight.legs[].segments[]. flightNumber string Yes Flight number without airline code prefix. In other words just digits e.g. 3861.
flight.legs[].segments[]. distance integer No Flown distance in land miles rounded to whole mile. If absent, the shortest distance between two airports will be calculated instead. Recommended to ensure best accuracy.
flight. price object No Required to ensure correct calculations for revenue-based frequent flyer programs. Strongly recommended.
flight.price. currencyCode string Yes ISO-4217 3-letter currency code
flight.price. total double Yes Total fare price for entire flight including taxes, fees, surcharges etc.
flight.price. fare double No Base fare price. Recommended to ensure best accuracy for revenue-based frequent flyer programs.
flight.price. taxes double No Total amount for all taxes.
flight.price. surcharges double No Total amount of surcharges imposed by the carrier.
programs[] array No Collection of frequent flyer program objects for which you want to calculate miles. Used to personalize results based on user memberships.
programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs. You can request list of programs with their codes using Programs method.
programs[]. tierCode integer No Code of status tier for specified frequent flyer program as in Appendix: Status tiers. Used to personalize calculations for users holding special status tier in a program e.g. Silver Status. If not specified, default, basic status tier will be used.
applyAllPrograms boolean No If set true and programs[] array is absent or empty, then all applicable combinations of frequent flyer program and its status tiers will be returned (not only pair of default program and basic status tier as in CalculateMixed method).
clientUserId string No Unique user id to link subsequent requests to the same person. Strongly recommended.

Response structure

Sample response

{
  "Success": true,
  "Status": {
    "Code": 0,
    "Message": "OK"
  },
  "Value": {
    "uniqueId": "56cbd707-66de-4b94-a132-4a7650ed3c67",
    "flights": [{
      "flightId": "SK1674-SK0503",
      "programs": [{
        "programCode": "SEB",
        "tierCode": 1,
        "earnings": {
          "earnings": [{
            "metricCode": 1,
            "value": 5250
          },{
            "metricCode": 2,
            "value": 5250
          },{
            "metricCode": 3,
            "value": 2
          }]
        },
        "upgrades": {
          "options": [{
            "targetFareType": 48,
            "totalCost": 10000,
            "details": [{
              "targetId": "SK1674-SK0503",
              "legLevel": true,
              "cost": 10000
            }]
          }]
        }
      },{
        "programCode": "SEB",
        "tierCode": 8,
        "earnings": {
          "earnings": [{
            "metricCode": 1,
            "value": 7540
          },{
            "metricCode": 2,
            "value": 7540
          },{
            "metricCode": 3,
            "value": 2
          }]
        },
        "upgrades": {
          "options": [{
            "targetFareType": 48,
            "totalCost": 8000,
            "details": [{
              "targetId": "SK1674-SK0503",
              "legLevel": true,
              "cost": 8000
            }]
          }]
        }
      },{
        "programCode": "AKA",
        "tierCode": 1,
        "earnings": {
          "earnings": [{
            "metricCode": 1,
            "value": 4200
          },{
            "metricCode": 3,
            "value": 2
          }]
        }
      }]
    }],
    "programs": [{
      "programCode": "SEB"
    },{
      "programCode": "AKA"
    }],
    "errors": []
  }
}

Property Value Required Description
Success boolean Yes True if request has been executed successfully
Status object Yes Contains status of executed method
Status. Code integer Yes Response status code as in Appendix: Status codes.
Status. Message string Yes Human-readable message describing response status.
Value object No Contains frequent flyer information for specified (or default) pairs of frequent flyer program and status tier. May be absent in case of error.
Value. uniqueId string Yes Unique id generated for every request.
Value. flights[] array Yes Collection of flights containing frequent flyer information.
Value.flights[]. flightId string Yes Unique id of the flight specified in request.
Value.flights[]. programs[] array No Collection of objects with frequent flyer information for particular frequent flyer program and its certain status tier.
Value.flights[].programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value.flights[].programs[]. tierCode integer Yes Code of status tier for specified frequent flyer program as in Appendix: Status tiers. By default only basic status tier is returned.
Value.flights[].programs[]. earnings object No Object containing frequent flyer earnings (miles). Absent if calculateEarnings flag in request is false or not set.
Value.flights[].programs[].earnings. earnings[] array Yes Collection of objects with frequent flyer earnings (miles). Each object contains earnings for different accrual (type of earned miles).
Value.flights[].programs[].earnings.earnings[]. metricCode integer Yes Code of accrual (type of earned miles) as listed in Appendix: Accrual types.
Value.flights[].programs[].earnings.earnings[]. value double Yes Number of earned frequent flyer miles or points. In some cases it may be a decimal.
Value.flights[].programs[]. upgrades object No Object containing eligibility of cabin upgrades. Absent if calculateUpgrades flag in request is false or not set.
Value.flights[].programs[].upgrades. options[] array Yes Collection of cabin upgrade options e.g. upgrade to Economy is one option, upgrade to Business is another.
Value.flights[].programs[].upgrades.options[]. targetFareType integer Yes Code of target fare type (cabin) as listed in Appendix: Fare families.
Value.flights[].programs[].upgrades.options[]. totalCost integer Yes Cost of entire upgrade option in redeemable miles used in particular frequent flyer program.
Value.flights[].programs[].upgrades.options[]. details[] array Yes Collection of upgrade objects for particular, eligible flight leg and/or segment.
Value.flights[].programs[].upgrades.options[].details[]. targetId string Yes Unique id of flight leg or segment specified in request (or generated if absent). Indicates which fragment of entire flight is eligible for an upgrade.
Value.flights[].programs[].upgrades.options[].details[]. legLevel boolean Yes True if targetId field relates to flight leg. False if it relates to flight segment.
Value.flights[].programs[].upgrades.options[].details[]. cost integer Yes Cost of single leg or segment upgrade in redeemable miles used in particular frequent flyer program.
Value.flights[].programs[]. benefits object No Object containing frequent flyer benefits. Absent if calculateBenefits flag in request is false or not set.
Value.flights[].programs[].benefits. benefits[] array Yes Collection of frequent flyer benefits groupped by benefit type (Appendix: Benefit types).
Value.flights[].programs[].benefits.benefits[]. targetId string Yes Unique id of flight leg or segment specified in request (or generated if absent). Indicates which fragment of entire flight has particular benefit type.
Value.flights[].programs[].benefits.benefits[]. legLevel boolean Yes True if targetId field relates to flight leg. False if it relates to flight segment.
Value.flights[].programs[].benefits.benefits[]. code string Yes Benefit type code as in Appendix: Benefit types.
Value.flights[].programs[].benefits.benefits[]. options[] array Yes Eligible benefits for particular benefit type and particular flight fragment (segment or leg). In majority of cases there is only one benefit available. There might be more options e.g. when passenger is eligible to access two different lounges on one airport.
Value.flights[].programs[].benefits.benefits[].options[]. name string Yes Name specific for particular frequent flyer program e.g. OneWorld S7 Lounge Access. If you need more generic name, use benefit type name provided in Benefits method.
Value.flights[].programs[].benefits.benefits[].options[]. disclaimer[] array No Array of strings with special conditions or restrictions for the benefit. In English.
Value.flights[].programs[].benefits.benefits[].options[]. guests integer Yes Maximum number of guests travelling with member eligible for particular benefit.
Value.flights[].programs[].benefits.benefits[].options[]. quantity integer No Number of extra pieces of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. weightMetricType string No Weight unit used for baggage restrictions (kg or lb). Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. weight integer No Maximum weight of one extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. totalWeight integer No Total maximum weight of all pieces of extra baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. sizeMetricType string No Length unit used for baggage restrictions (cm or in). Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. sizeWidth integer No Maximum width of extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. sizeLength integer No Maximum length of extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. sizeHeight integer No Maximum height of extra piece of baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value.flights[].programs[].benefits.benefits[].options[]. totalLength integer No Maximum sum of dimensions of every piece of extra baggage. Set only for XTRBGG benefit type (extra baggage allowance).
Value. programs[] array Yes Collection of basic information about frequent flyer programs used in response. For more detailed information and full list of programs, you need to use Programs method. Array may be empty if there were no programs earning to any of specified flights.
Value.programs[]. programCode string Yes Frequent flyer program 3-letter code, that you can find in Appendix: Frequent flyer programs.
Value. errors[] array Yes Collection of error objects for specific flights (if any occured).
Value.errors[]. flightId string Yes Unique id of the flight specified in request.
Value.errors[]. code string Yes Error code indicating problem encountered when processing flight information in request. See all error codes listed in Appendix: Error codes.
Value.errors[]. message string Yes Human-readable message for debugging purposes.

Appendices

Frequent flyer programs

A list of all supported frequent flyer programs and their respective codes used in the API.

You can always use the Programs method to retrieve an up to date list of all programs along together with any additional information, for example, status tier levels and their required thresholds.

Program code Program name
AMB Aegean Airlines Miles+Bonus
LGC Aer Lingus AerClub
AFL Aeroflot Bonus
ARP Aerolíneas Plus
MCP Aeromexico Club Premier
ARD Air Arabia Airewards
ACA Air Canada Altitude/Aeroplan
ACP Air China PhoenixMiles
UXS Air Europa SUMA
AKF Air France/KLM Flying Blue
IFR Air India Flying Returns
NZA Air New Zealand AirPoints
UKV Air Vistara Club Vistara
AKB AirAsia BIG Loyalty
AMP Alaska Airlines Mileage Plan
AMM Alitalia MilleMiglia
AAA American Airlines AAdvantage
AMC ANA Mileage Club
ASC Asiana Club
ALM Avianca LifeMiles
BBL Belavia Belarusian Airlines Belavia Leader
BAC British Airways Executive Club
CXA Cathay Pacific Marco Polo Club/AsiaMiles
CDF China Airlines Dynasty Flyer
CEM China Eastern Eastern Miles
SPC China Southern SkyPearl Club
CCM Copa Airlines ConnectMiles
OKP Czech Airlines OK Plus
DSM Delta SkyMiles
MSP EgyptAir Plus
EAM El Al Matmid
EKS Emirates Skywards
ETS Ethiopian Airlines ShebaMiles
EYG Etihad Airways Guest
EWB Eurowings Boomerang Club
IML EVA Air Inifinity MileageLands
FPL Finnair Plus
FMF Frontier Airlines Frontier Miles
GFF Garuda Indonesia GarudaMiles
GOS GOL Smiles
FWC Hainan Airlines Fortune Wings Club
IBP Iberia Plus
JMB JAL Mileage Bank
JRP Jeju Air Refresh Point
JJP Jet Airways JetPrivilege
JTB JetBlue TrueBlue
KSP Korean Air Skypass
KOC Kuwait Airways Oasis Club
LAP LATAM Pass Program
LMM Lufthansa Miles & More
MHE Malaysia Airlines Enrich
MEA Middle East Airlines Cedar Miles
NRW Norwegian Air Shuttle Norwegian Reward
PMM Philippine Airlines Mabuhay Miles
QFF Qantas Frequent Flyer
QAP Qatar Airways Privilege Club
RJP Royal Jordanian Royal Plus
SPR S7 Priority
SEB SAS EuroBonus
SVA Saudi Arabian Airlines Alfursan
SKF Singapore Airlines KrisFlyer
SAV South African Airways Voyager
SFS Spirit Airlines Free Spirit
SAF SriLankan Airlines FlySmiLes
SCU Sun Country Airlines Ufly Rewards
TMF LATAM Fidelidade
TPV TAP Miles&Go
ROP Thai Airways Royal Orchid Plus
MAS Turkish Airlines Miles&Smiles
UMP United Airlines MileagePlus
GLP Vietnam Airlines Lotusmiles
VFC Virgin Atlantic Flying Club
VAV Virgin Australia Velocity Frequent Flyer
WSR WestJet Rewards
MFE Xiamen Airlines Egret Club

Status tiers

A list of abstract status tiers used in the API across all frequent flyer programs.

The actual names of status tiers tend to be branded and vary between programs (see the Programs method).

Tier code Name for internal usage
0 Unknown
1 Basic
8 Tier1 Silver
16 Tier2 Gold
24 Tier3 Platinum
32 Tier4 Diamond
33 Tier5
34 Tier6
35 Tier7

HTTP status codes

The most common HTTP status codes you may encounter in response.

HTTP status code Name Description
200 OK Operation completed without any critical errors
400 Bad Request Request is invalid and can’t be processed
500 Internal Server Error Error on server side aborting operation. If you encounter any, please contact our support to resolve the issue.

Status codes

Codes used to ensure, that response was processed successfully.

Status code Description
0 Operation was successful. Always in conjunction with 200 HTTP status code.
-1 Operation finished with error while processing request. Always in conjunction with 400 or 500 HTTP status code.

Accrual types

Also known as types of miles. You can retrieve program-specific names of these accrual types using the Programs method.

Accrual code Accrual name
1 Redeemable Miles (RDM). Redeemable miles are the most common ones. The only ones used to redeem for free flights, cabin upgrades or other passenger benefits.
2 Elite Qualifying Miles (EQM). Elite qualifying miles are collected to reach certain threshold needed for particular status tier in a program e.g. after collecting 50,000 EQM you become Silver member (you reached Silver status tier).
3 Elite Qualifying Segments (EQS). Elite qualifying segments have the same purpose as EQM, but are collected based on flown flight segments instead of distance.
4 Elite Qualifying Points (EQP). Elite qualifying points have the same purpose as EQM, but have earning different rules.
5 Elite Qualifying Dollars (EQD). Elite qualifying dollars have the same purpose as EQM, but they are related to purchased fare price, not neccessarily the flown distance.

Error codes

Error codes returned in response to any calculate method, such as CalculateMiles.

Error code Description
FLEMP Flights collection is empty.
FLIDE The flightId field is not set for some flight(s).
FLTPE Flight doesn’t have total price specified in the price block.
FLLGE Legs are not set for some flight(s).
FLSGE Segments are not set for some flight(s).
FLSGDAE Departure airport code is either not set or has not been provided in IATA format.
FLSGAAE Arrival airport code is either not set or has not been provided in IATA format.
FLSGMKE Marketing airline code is either not set or has not been provided in IATA format.
FLSGOPE Operating airline code is either not set or has not been provided in IATA format.
FLSGFCE The fare code is not set for some flight(s).
FLSGDDE Departure date is either not populated or set in invalid format.
FLSGFNE The flight number is not set for some flight(s).
PCUKNW Unknown program code detected.
PTUKNW Unknown program status tier code detected.

Airline alliances

A list of airline alliances with their respective codes used in, for instance, the Programs method.

Alliance code Alliance name
0 Unknown
1 Independent (does not belong to any alliance)
2 OneWorld
3 SkyTeam
4 StarAlliance

Fare families

A list of fare families used in methods related to cabin upgrade, for instance, CalculateUpgrades.

Fare family code Fare family name
0 Unknown
8 Discount Economy
16 Economy
24 Full Economy
32 Premium Economy
40 Discount Business
48 Business
52 Premium Business
56 First
64 Premium First

Benefit types

A list of supported benefit types used in methods that calculate frequent flyer benefits, such as CalculateBenefits.

You can use Benefits method to retrieve this list, along with additional information.

Code Name Description
CMPCHG Complimentary flight change Complimentary same day flight changes to earlier or later flights
LNGACS Lounge access Admission to the airport lounge while waiting to board
PFDSTG Preferred seating Reserve your preferred seating when checking in (subject to airline availability)
PRMBRG Premium beverage Complimentary premium beverage
PTYBDG Priority boarding Admission to use the priority lane to board
PTYBDO Priority baggage handling Your baggage will be tagged to be among the first to arrive on the carousel
PTYCHK Priority check-in Admission to use the priority lane at the check-in counter
PTYDSK Priority at transfer desks Enjoy seamless transfers between your flights
PTYIMM Fast track immigration Admission to use the fast or priority lane at immigration
PTYSTY Fast track security Admission to use the fast or priority lane at the security checkpoint
XTRBGG Extra baggage allowance Allowed extra baggage in addition to the standard allowance of the fare class, free of charge
XTRLRM Extra legroom Reserve spacious seating when checking in (subject to airline availability)

Release notes

Version 2.6

  1. Added new method: Benefits.
  2. Modified CalculateBenefits, CalculateOneBenefits, CalculateMixed and CalculateOneMixed methods. Response containing frequent flyer benefits allows multiple benefit options per one benefit type e.g. when passenger can access two different lounges on the same airport.

Version 2.5

  1. Added new methods: CalculateBenefits, CalculateOneBenefits,
  2. Modified methods: CalculateMixed, CalculateOneMixed. Added capability to return frequent flyer benefits,
  3. Parameters in API request and properties in API response has been entirely rewritten. Full names replaced abbreviations,
  4. Added applyAllPrograms parameter to CalculateOne requests e.g. in CalculateOneMiles. By default CalculateOne methods return frequent flyer information based only on marketing airline frequent flyer program, not all possible combinations of programs and status tiers as it was before.

Version 2.4

  1. Added new methods: CalculateUpgrades, CalculateOneUpgrades, CalculateMixed, CalculateOneMixed.