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 with FastX codes, 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. These rules are managed through the Preference App, which is already pre-installed and ready to use for you in the "My Apps" section of the Travelgate Store.

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.

Typical Use Cases

• Prioritize Direct Contracts: Give an advantage to your direct hotel contracts over third-party redistributors, even if the direct price is slightly higher.
• Supplier Commercial Agreements: Honor volume commitments or overrides with specific Partners by ensuring their results appear more frequently in your top options.
• Strategic Filtering: Automatically discard all competitors when a preferred supplier offers a rate within a specific price tolerance (Filter Competitors).
• Currency Harmonization: Compare prices from suppliers using different currencies in real-time to find the truly most competitive option.
• Destination-Based Strategy: Prioritize a specific supplier for key destinations or countries (e.g., a local specialist in Spain). You can ensure their hotels are selected even if their price is up to X% higher than global aggregators.

Preference Plugin Workflow

The Preference Plugin follows a 5-step logic to ensure your preferred suppliers win the booking, even if they don't have the lowest market price.

1. Rule Fetching: The system retrieves your custom rules—such as tolerance percentages, specific suppliers, or target destinations—directly from the Travelgate database.

2. Price Adjustment (the "virtual" calculation): For every option returned by suppliers, the plugin checks for a match with your rules. If a match is found, it applies a tolerance factor to calculate a "virtual price": If a rule gives a 10% advantage to Supplier A, a $100 room is internally treated as $90. ⚠️ Important: This calculation is internal only. The final price shown to your customer in the response is always the original supplier price ($100).

3. Strategic Ranking: The system ranks all options from cheapest to most expensive based on these Virtual Prices. This allows your preferred suppliers to "climb" to the top of the list, even if their real price is higher.

4. Selection (Options per Key): The plugin selects the top "n" results (4 by default, though this is configurable via optionsPerKey). Because of the Virtual Price adjustment, your preferred options are now prioritized within this selection.

5. Competitor Filtering (optional): If the "Filter Competitors" setting is active and an option matches a preference rule, the system will discard all other competing offers for that specific group (hotel/room/board). In this case, your preferred supplier will be the only one returned.

Can I have an example on how a preference rule would work?

Primary Key used: hotel, room, board

Options per key: 2

Preference Rule Loaded: Tolerance Percentage = 1% for all supplier "SUP1" hotels. The 'filterCompetitors' option is enabled.

Scenario:

• Supplier SUP1 offers 126€ for Hotel Santo Domingo (Double Room, All Inclusive).
• Supplier SUP2 offers 125€ for Hotel Santo Domingo (Double Room, All Inclusive).

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: Hotel Santo Domingo, room: Double Room, board: 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 (as 'optionsPerKey' = 2).

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

1. Create your Preference Rules on our Travelgate website

Your searches will apply the Preference rules you create using the Preference App. This app is already pre-installed and ready to use for you in the "My Apps" section of the Travelgate Store.

Within the app, you can:

• View all your existing rules.
• Create new ones.
• Edit or delete existing rules.
• Configure a Tiebreaker — a priority list of suppliers that determines which one to keep in case multiple options are equally ranked after applying your rules.

Creating or editing a rule is done through a simple 3-step form within the Preference App. Each step defines how and when your rule will be applied.

Step 1. Rule Name

Give your rule a clear and identifiable name. This name will help you easily recognize it later when managing or prioritizing your rules.

Step 2. Rule Configuration

This step defines both the conditions under which your preference will apply and the preference behavior itself.

2.1. Target Criteria

Specify the conditions that must be met for this preference rule to apply. Here, you can define:

• Supplier(s): The supplier(s) to which the preference should apply.
• Hotel Filters (optional): You can narrow down the rule to specific hotel codes or even to hotels within a certain country.
• Date Filters (optional): Define booking or check-in date ranges for which this preference should be valid.
• Rate Filters (optional): Apply the preference only to certain rate conditions (e.g., non-refundable, package, etc.).

These filters allow you to create very specific preference behaviors based on your business strategy.

2.2. Preference Settings

Define how your preference should affect the supplier’s competitiveness:

• Percentage: This value determines the adjustment applied when comparing suppliers under the defined criteria.

  • A positive percentage gives an advantage to options that meet this rule’s conditions — they will be considered more competitive.
  • A negative percentage makes those options less competitive compared to others.

• Filter Competitors: When set to true, if at least one option in the group matches this rule’s conditions, that option will automatically be selected, and all others will be discarded.

Step 3. Review and Create the Rule

Before saving, review all your configurations. Once confirmed, click Create Rule. You can edit or delete the rule at any time, or even assign it a higher priority than other existing rules. Rules are processed in ascending numerical order (lower numbers are evaluated first), meaning priority 0 is executed first. Therefore, the lower the number, the higher the priority.

Additionally, you can access logs to track which user created or modified each rule and when the change occurred.

2. Execute Preference Plugin in your Query

Once you've uploaded your preference rules in the website, 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"
                        },
						{
                            "key" : "optionsPerKey",
                            "value" : "2"
                        },
						{
                            "key" : "internalCurrencyConversion",
                            "value" : "true"
                        }
                    ]
			}
		}
	]
}

Rule Configuration Examples

The following examples demonstrate how to configure different preference strategies using the Preference App.

Example 1. Prioritize a local specialist in a specific country

Use case: Prioritize a specialist supplier in Spain (SUP1) by giving them a competitive advantage, even if their price is up to 0.75% higher than other suppliers.

Rule configuration:

Step	Configuration
Target criteria (Step 2.1)	Supplier: SUP1 Country: ES
Preference percentage (Step 2.2)	Percentage: 0.75% Filter competitors: False

Evaluation:

• If SUP1 offers a hotel in Spain, its price is internally reduced by 0.75% for ranking purposes.
• The final response will still show the original price.
• All other search requests or destinations are not affected by this rule.

Example 2. Aggressive strategy for direct contracts

Use case: If a direct contract supplier (SUP_D) provides a price within a 2% margin of any competitor, discard all other options and show only the direct contract.

Rule configuration:

Step	Configuration
Target criteria (Step 2.1)	Supplier: SUP_D Hotel: All hotels
Preference percentage (Step 2.2)	Percentage: 2% Filter competitors: True

Evaluation:

• If SUP_D is within 2% of the cheapest competitor, all other suppliers for that group are discarded.
• Only the option from SUP_D is returned in the response.

Example 3. Seasonal promotion for specific check-in dates

Use case: Boost a specific supplier (SUP-SUMMER) during the high season in Italy.

Rule configuration:

Step	Configuration
Target criteria (Step 2.1)	Supplier: SUP-SUMMER Country: IT Check-in: 2028-06-01 to 2028-08-31
Preference percentage (Step 2.2)	Percentage: 3% Filter competitors: False

Evaluation:

• Options from SUP-SUMMER for these dates/destinations receive a 3% internal price improvement.
• This increases the probability of this supplier being among the top options returned based on the optionsPerKey parameter.

Best Practices for Rule Configuration

To ensure optimal performance and maintain a clean business strategy, we recommend following these best practices when configuring your Preference rules:

1. Start with Broad Rules, then Refine: Begin by creating general preference rules (e.g., for a specific supplier globally) before adding granular filters like specific hotel codes or check-in dates. This helps you understand the baseline impact on your results before fine-tuning.

2. Use "Filter Competitors" Sparingly: The Filter Competitors option is a powerful tool. Use it only when you have high confidence in a supplier's availability and price (e.g., Direct Contracts). If a rule filters out all competitors and the preferred supplier's option fails during the booking flow, you may lose the sale.

3. Monitor your "optionsPerKey": Remember that the Preference Plugin works in tandem with the optionsPerKey parameter. If you set a high preference percentage but a low optionsPerKey (e.g., 1 or 2), you might be unintentionally hiding competitive rates that could be useful for your customers.

4. Optimize Aggregation with "primaryKey": The choice of primaryKey is crucial for the "Virtual Price" comparison. Pro-tip: Including room and board in your primaryKey ensures you are comparing "apples to apples". Comparing a "Room Only" rate against an "All Inclusive" rate via preference rules can lead to misleading ranking results.

5. Leveraging Negative Percentages: Don't just think about who you want to win. Use negative percentages (e.g., -2%) to de-prioritize suppliers with low profit margins or poor operational performance without removing them from your inventory entirely.

6. Review Rule Priority and Ties: If multiple rules apply to the same option, the system evaluates them based on priority. Regularly review your Tiebreaker settings in the Preference App to ensure that, in case of a draw after all recalculations, the most strategic supplier is still selected.