Skip to main content

HotelX Settings

In all booking flow and booking management requests, you'll find certain fields that you need to fill in. These include the HotelSettingsInput and criteria inputs. These fields contain various elements, some of which are known as settings. These settings are the common configurations used to construct your requests to the supplier/s. They consist of fields that are frequently needed, like language, currency, and timeout.

You have the flexibility to fill in these settings with different values for each of your query and mutation requests. However, to make things easier, you can also choose not to fill them in every time, especially if you know the values will remain the same. In such cases, we have default settings. These default settings are the values we'll use in the background if you don't specify the fields that are part of these settings.

Remember!

When you begin using Travelgate, these settings are automatically created, but it's essential to review and update them according to your preferences in our API Settings website section.

Settings fields​

We'll clarify which fields are categorized as settings and where you can locate them. We'll also specify whether it's mandatory to provide a value for each field or if you have the option to leave it empty, in which case the default settings will be applied:

Context Mode

Use the Context Decision Matrix to decide whether to use FASTX, Buyer context, or Supplier context.

FieldMandatory / Optional / ConditionalWhere to Fill It
clientMandatoryQuery (Settings input)
contextConditionalQuery (Settings input) or Default Settings. In FastX, it can be omitted when sending FastX hotel codes.
timeoutMandatoryQuery (Settings input) or Default Settings will be used
businessRulesMandatoryQuery (Settings input) or Default Settings will be used
languageMandatoryQuery (Criteria input) or Default Settings will be used
currencyMandatoryQuery (Criteria input) or Default Settings will be used
nationalityMandatoryQuery (Criteria input) or Default Settings will be used
marketsMandatoryQuery (Criteria input) or Default Settings will be used
optionsQuotaOptionalQuery (Criteria input), default settings or 300 will be used as value. This sets the maximum number of options returned per board in a search. If not specified in the query, the system will use the value from your HotelX API default settings. If no value is set there, the system will default to 300 options.
useOnlyValidatedFastXCodesOptionalConfigurable only in the API Settings section on the website. Default: false. Controls which FastX hotel and board codes are accepted in your booking flow. See FastX codes validation modes below.

FastX codes validation modes​

The useOnlyValidatedFastXCodes setting has two modes:

ValueModeCodes allowed in booking flow
falseDefault Mode (recommended)Validated + Pending
trueValidated-only ModeValidated only

FastX mapping statuses:

  • Validated — Seller confirmed the suggested mapping is correct
  • Pending — Awaiting Seller review; accepted in Default Mode
  • Invalidated — Seller rejected the mapping; always blocked by Travelgate

To understand how Sellers assign these statuses and what each means for your booking flow, see FastX Codes.

Default settings levels​

Understanding the various levels at which default settings can be applied is crucial for tailoring your configurations precisely to your needs:

  1. Organization/Group Level: Settings at this level apply to the entire organization or HotelX group.

HotelX groups refer to a group of clients to which you can apply different business rules. By default, as a Buyer, you only have one HotelX group. You don’t need to worry about having more than one unless you have very specific business needs. If you do, please contact our Customer Care team.

  1. Client Level: Settings at this level are specific to individual clients. This means that default settings set for a particular client will only affect that client.

  2. Supplier Level: These settings are tailored to specific suppliers. Default settings set for a particular supplier will impact all accesses associated with that supplier.

  3. Access Level: Settings set at this level apply to a specific access. This implies that they will only affect that access. These settings take precedence over settings at the organization/group, client, and supplier levels.

  4. Query/Mutation Level: These settings are those you, as a Buyer, specify in your query or mutation. Regardless of the default settings configured at other levels, these settings take precedence and will override them.

warning

Settings defined in your API request (at the query or mutation level) override all other default settings. The priority order (from highest to lowest) is: Query/Mutation > Access > Supplier > Client > Organization.

Read and update settings via API​

You can also manage your default HotelX settings directly via GraphQL, without using the platform UI.

The API exposes two settings families:

  • defaultSettings: Organization and Client levels.
  • commonSettings: Supplier and Access levels.
Recommended workflow
  1. Read current settings first.
  2. Apply your update mutation.
  3. Read again to confirm the final values.

1. Read Organization or Client defaults​

Use defaultSettings to retrieve defaults at Organization level (group) or at Client level (group + clientName).

query ReadDefaultSettings {
  hotelX {
    defaultSettings(group: "YOUR_GROUP_ID", clientName: "client_demo") {
      settings {
        context
        language
        currency
        nationality
        markets
        validatedDataOnly
        timeout {
          search
          quote
          book
        }
      }
      adviseMessage {
        code
        message
      }
    }
  }
}

2. Read Supplier or Access defaults​

Use commonSettings to retrieve defaults for:

  • a supplier: group + supplier
  • a specific access: group + access
query ReadCommonSettings {
  hotelX {
    commonSettings(group: "YOUR_GROUP_ID", supplier: "YOUR_SUPPLIER_ID") {
      settings {
        currency
        markets
        timeout {
          search
          quote
          book
        }
      }
      adviseMessage {
        code
        message
      }
    }
  }
}

3. Create or update Organization/Client defaults​

For Organization and Client levels, use:

  • createDefaultSettings when the record does not exist yet.
  • updateDefaultSettings when you want to modify an existing record.
mutation UpdateClientDefaultSettings {
  hotelX {
    updateDefaultSettings(
      group: "YOUR_GROUP_ID"
      clientName: "client_demo"
      settings: {
        language: "en"
        currency: "EUR"
        nationality: "ES"
        markets: ["ES"]
        validatedDataOnly: false
        timeout: { search: 12000, quote: 12000, book: 18000 }
      }
    ) {
      settings {
        language
        currency
        nationality
        markets
        validatedDataOnly
      }
      adviseMessage {
        code
        message
      }
    }
  }
}

4. Create or update Supplier/Access defaults​

For Supplier and Access levels, use:

  • createCommonSettings
  • updateCommonSettings

Use either supplier or access depending on the level you want to manage.

mutation UpdateAccessCommonSettings {
  hotelX {
    updateCommonSettings(
      group: "YOUR_GROUP_ID"
      access: "YOUR_ACCESS_ID"
      settings: {
        currency: "EUR"
        markets: ["ES", "PT"]
        timeout: { search: 10000, quote: 10000, book: 15000 }
      }
    ) {
      settings {
        currency
        markets
        timeout {
          search
          quote
          book
        }
      }
      adviseMessage {
        code
        message
      }
    }
  }
}
Scope note

In these operations, group refers to your HotelX group. For common settings, target one specific scope at a time (Supplier or Access) to avoid configuration mistakes.

Naming note

In API schema, the field is validatedDataOnly. In API Settings UI and functional documentation, this behavior is described as useOnlyValidatedFastXCodes.

info

You can configure and adjust all these default settings at the API Settings section on our website.

Overriding settings for a specific supplier in your request​

As explained above, any setting you send at the Query/Mutation level (for example, currency inside your criteria) takes priority over any default settings, regardless of the level at which they were configured.

You can also go further and override some of these fields for a single supplier (or a single access of that supplier) using the suppliers field of the HotelSettingsInput (settings).

Important

A field sent in criteria (such as currency) is used for every supplier in the request and always wins, even over a suppliers[] override for that same field. The suppliers[] override for a given field only has an effect when that field is not sent in criteria.

This means that if your system always sends currency in criteria and can't leave it empty, there's no way to force a different currency for a single supplier in that same request — the value in criteria will be sent to all suppliers regardless of any suppliers[] override.

To force a different currency for one specific supplier, you must omit currency from criteria entirely, and set it individually via the suppliers field instead. Suppliers you don't list there will fall back to whatever default settings are configured for them (org/client/supplier/access level).

warning

Setting suppliers[].settings alone, without listing any accesses, has no effect. You must always include the accesses node for the override to be applied — either by setting the value per access, or by listing the accesses that should use the supplier-level value.

For example, if you don't send currency in criteria and need supplier HOTELTEST to receive USD for one of its accesses and BRL for another, set currency inside each access' own settings:

{
    "criteriaSearch": {
        "checkIn": "2026-10-28",
        "checkOut": "2026-10-29",
        "hotels": [
            "BR1518"
        ],
        "occupancies": [
            {
                "paxes": [
                    {
                        "age": 30
                    },
                    {
                        "age": 30
                    }
                ]
            }
        ],
        "language": "es",
        "nationality": "ES",
        "markets": [
            "ES"
        ]
    },
    "settings": {
        "client": "client_demo",
        "timeout": 11000,
        "suppliers": [
            {
                "code": "HOTELTEST",
                "accesses": [
                    {
                        "accessId": "2",
                        "settings": {
                            "currency": "USD"
                        }
                    },
                    {
                        "accessId": "3",
                        "settings": {
                            "currency": "BRL"
                        }
                    }
                ]
            }
        ]
    }
}

Alternatively, if you want the same override to apply to every access of that supplier, you can set currency once in the supplier-level settings, but you still need to list those accesses under accesses (without repeating the setting on each one) for it to take effect:

"settings": {
    "client": "client_demo",
    "timeout": 11000,
    "suppliers": [
        {
            "code": "HOTELTEST",
            "settings": {
                "currency": "USD"
            },
            "accesses": [
                { "accessId": "2" },
                { "accessId": "3" }
            ]
        }
    ]
}

Both approaches can be combined and used for multiple suppliers within the same suppliers array — for example, a shared currency for all accesses of one supplier, and a specific currency for a single access of another supplier:

"settings": {
    "client": "client_demo",
    "timeout": 11000,
    "suppliers": [
        {
            "code": "HOTELTEST",
            "settings": {
                "currency": "BRL"
            },
            "accesses": [
                { "accessId": "2" },
                { "accessId": "3" }
            ]
        },
        {
            "code": "TTHOTTEST",
            "accesses": [
                {
                    "accessId": "5647",
                    "settings": {
                        "currency": "EUR"
                    }
                }
            ]
        }
    ]
}

Each entry in suppliers (HotelXSupplierInput) is made up of:

  • code (mandatory): the code of the supplier the override applies to.
  • settings: the values to override for all the listed accesses of that supplier, unless a given access defines its own settings. It accepts currency.
  • accesses: the accesses of that supplier the override applies to. This is required — without it, suppliers[].settings is ignored. Each access can optionally define its own settings, which takes precedence over the supplier-level settings for that access only.
info

Supplier and access-level settings sent this way overwrite default settings, following this priority: access settings > supplier settings > default settings (Access > Supplier > Client > Organization). None of these levels can override a field also present in criteria/request-level settings, since that value is used for the whole request.