Skip to main content

Preference

The Preference Plugin is a more advanced and configurable version of the Cheapest Price Plugin. While the Cheapest Price Plugin selects the lowest-priced option/s based on defined criteria, the Preference Plugin allows you to prioritize certain options over others, even if they are not the absolute cheapest.

This is particularly useful when using Hotel-X in multi mode, where multiple suppliers may offer different prices for the same hotel, board, or room type. With the Preference Plugin, you can set preference rules that influence how results are ranked and selected.

For example, you might want to:

  • Prioritize a specific supplier for certain hotels, even if their price is up to X% higher.
  • Give preference to a supplier during specific dates or destinations.
  • Customize selection rules based on your business strategy.

By leveraging the Preference Plugin, you gain greater control over how options are selected, allowing you to fine-tune your results based on your own supplier relationships, pricing strategy, and business goals.

Preference Plugin Workflow​

  1. Gets the rules stored in database which will establish which options will be added or discarded based on several factors as % of tolerance of the price, hotel codes, supplier, etc.

  2. Go over each option returned by the suppliers and if it matches any of the rules recovered from database, their price will be recalculated by multiplying it by the tolerance factor set in the rule. For example, if the factor is 10%, the new price will be 90% of the original price. This recalculation of the price is only used for aggregation purposes—the final response will always return the original prices.

  3. Sorts the options in price order (from cheap to expensive) by the recalculated price.

  4. Take the first 'n' options (4 by default, configurable with the optionsPerKey parameter). That is, this will involve selecting the n cheapest options once the prices have been recalculated, taking the preference rules into account.

  5. There is only one exception to this, which is when a rule states that competitors must be filtered out. Thus, if any of the options meet such a rule, for that group of options, the option that filters out competitors will be the only one returned.

Example​

Preference Rule Loaded: Tolerance Percentage = 1% for all SUP1 hotels and 'filterCompetitors' is enabled.

Scenario:

  • Supplier SUP1 offers 126€ for Hotel Santo Domingo (Double Room, All Inclusive).
  • Supplier SUP2 offers 125€ for the same hotel and room type.

By default, SUP2 wins because it has the lowest price.
However, with the preference rule applied:

  1. We first group all options with the same aggregation primary key (Hotel Santo Domingo - Double Room - All Inclusive).

  2. Since there is a preference rule for SUP1 hotels, we recalculate the price and internally save it like:

    Formula:
    Option price * (100 - tolerance%) / 100
    `126€ * (100 - 1) / 100 = 124.74€

  3. Since 124.74€ is lower than 125€ and 'filterCompetitors' is enabled, the SUP2 option is discarded, making SUP1 the only returned option.

If 'filterCompetitors' were disabled, SUP1 would be added to the group, and both options would be returned in the results.

To get started with the Preference plugin, follow these simple steps:

1. Create and Upload your Preference File​

To get started, create your preference file in the correct format and then upload it to your SFTP account. We've provided a template file below ⬇️ to help you with this process. Just click on the file name, add your own rules, save it in CSV format, and then upload it to the corresponding folder in your SFTP.

sftp.xmltravelgate.com

📁HotelX
     📁HotelX_0000
         📁BusinessRules
             📄BuyerContext_sequential_preference.csv

note

If you need assistance with requesting your credentials to access the SFTP server, determining the endpoint and directory format, or learning how to upload, update, and delete SFTP files, please refer to the overview section of Plugins.

File Format Specification​

  • File Name: BuyerContext_sequential_preference.csv
  • Directory: HotelX/HotelX_0000/BusinessRules
  • Delimiter: Comma (,)
  • Header Row:
    • RuleId (mandatory): Rule identifier
    • ClientTokens: Identifier provided by the client that is used to filter which business rules can be applied for the sent request.
      • Separator for multiples codes in the same row: Semicolon ;
    • SupplierCodes (mandatory): Supplier codes you want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • NotSupplierCodes (mandatory): Supplier codes you don't want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • BookingDateFrom: Booking date from (yyyy-mm-dd)
    • BookingDateTo: Booking date to (yyyy-mm-dd)
    • StartDateFrom: Start date from (yyyy-mm-dd)
    • StartDateTo: Start date to (yyyy-mm-dd)
    • HotelCodes: Hotel codes you want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • NotHotelCodes: Hotel codes you don't want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • ChainsCodes: Chain codes you want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • NotChainCodes: Chain codes you don't want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • DestinationCodes: Destination codes you want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • NotDestinationCodes: Destination codes you don't want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • Status: Option status (OK, RQ) you want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • NotStatus: Option status (OK, RQ) you don't want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • Percentage (mandatory): Commission value, decimal separator must be point .. Percentage represents the tolerance you allow over the net price to avoid discarding the option. In other words, options that meet the criteria of this rule will not be discarded, even if they are up to X% more expensive than the cheapest option.
    • FilterCompetitors (mandatory): true/false value. If set to true, it means that if an option exists that meets the criteria of this rule, only that option will be kept, and all others will be discarded. This ensures you only retain the option that follows the rule's criteria.
📹Learn how to change the format of the csv file in order to edit and save it

2. Execute Preference Plugin in your Query​

Once you've uploaded your preference file, to use the plugin add the following field to the settings node of your request. Note that preference plugin can just be executed in search query. In order to successfully execute the preference plugin, you will need to create the request with the following variables.

  • step: "RESPONSE"
  • type: "PRE_STEP"
  • name: "preference"
  • parameters:

    • primaryKey: Criteria used to aggregate, separated by commas. For example: "hotel, supplier, board". Possible values are:

      • hotel
      • supplier
      • board
      • binding
      • cancelPolicy
      • currency
      • market
      • payment
      • promotion
      • rateRules
      • refundable
      • room
      • supplement
      • surcharges
      • ratePlan
      • status

    • optionsPerKey: Limits the number of options per aggregation group, this being defined by the previous primakyKey parameter. Value: Integer. By default it is 4.

    • internalCurrencyConversion: Enables internal currency conversion for aggregation. Value: true or false. By default, aggregation considers the currency, meaning that only options sharing the same currency are grouped together. If you receive responses from multiple suppliers using different currencies but want to internally compare them, you can enable this option. When set to true, Travelgate will apply an internal currency conversion (updated every day) to allow aggregation and comparison of options within the same primaryKey group, even if they have different currencies. This conversion is only used for aggregation purposes—the final response will always return prices in their original currency.

Remember

primaryKey is a mandatory parameter in order to activate the plugin. optionsPerKey and internalCurrencyConversion are optional and complementary of the first.

"settings": {
	"plugins": [
		{
			"step": "RESPONSE",
			"pluginsType": {
				"type": "PRE_STEP",
				"name": "preference",
            "parameters" : [
                        {
                            "key" : "primaryKey",
                            "value" : "hotel,board,room"
                        }
                    ]
			}
		}
	]
}

Special Aggregation Key: eqRates​

There is a special value for the aggregation key "eqRates" that will combine the rateRules and ratePlans of an option and group all of the options, based on the file uploaded in the SFTP with the name:

sftp.xmltravelgate.com

📁HotelX
     📁HotelX_0000
         📁BusinessRules
             📄SupplierContext_rateplanraterule.csv

With this uploaded CSV file, all the options with the ratePlan code "NOREEMBOLSABLE" and no rateRules will be compared with each other. Similarly, all the options without a ratePlan code or without a mapped ratePlan and with rateRules set to "NON_REFUNDABLE" will also be compared with each other.