How to implement language selection

Introduction

When selling tours and activities, offering the right tour-language options helps improve the customer experience. The Tiqets API provides language availability for each product and its variants, allowing you to display a language selector only when it makes sense.

This guide walks you through how to retrieve available languages, display a selector, and ensure customers book the right variant in their preferred language.

Why Show a Language Selector?

A language selector is more than just a convenience, it directly impacts user experience and conversions.

✅ Better Customer Experience – Customers can confidently choose a product that supports their language. ✅ Fewer Booking Issues – Prevents misunderstandings about the language spoken during the tour and therefore customer support requests. ✅ Increased Sales – Making it easier for customers to find their preferred language reduces drop-offs before or during checkout. ✅ Transparency – Clearly showing supported languages sets the right expectations before booking.

By integrating a language selector, you help customers make informed decisions and reduce frustration at the time of the experience.

1. Checking Available Languages for a Product

Before showing a language selector, we need to check which languages are available for a product and if you should display the language selector for it.

You can do this by calling the Content API:

GET https://api.tiqets.com/v2/products/1109115

Response:

{
    "product_id": 1109115,
    ...
    "language_selection": [
        "eng",
        "spa"
    ]
}

The language_selection field lists available languages in 3-letter format (ISO 639-3).
This field show values only when the language selection is shown on tiqets.com This approach help you rely on one key information only to know if you should display the language selector or not. We curate for you this decision so you do not have to build complex logic to decide when to show it or not..

The Product and Variant data structures contain multiple fields related to language but those are unrelated to the subject of language selection covered by this guide.

For details on the purpose of the various fields, please see the individual field descriptions in the API Reference.

2. Checking which Languages are Available for Specific Variants

When a product supports multiple languages, it’s important to guide customers through language selection before showing availability details. This ensures they only see relevant dates, times, and variants, making the booking experience smooth and intuitive.

Since language filtering must be handled on the backend, API users should first retrieve the available languages, then display a language selector before showing availabilities.

To check which variants support which languages, use the Availability API:

GET https://api.tiqets.com/v2/products/1109115/availability

Response:

{
    "product_id": 1109115,
    "variants": [
        {
            "variant_id": "12345",
            "language_selection": [
                "eng"
            ]
        },
        {
            "variant_id": "67890",
            "language_selection": [
                "spa"
            ]
        }
    ]
}

Filtering availability based on language should happen on your end – Tiqets does not provide a query parameter for filtering by language.
Each variant lists its own available languages under the language_selection field.
If the language_selection field is missing for a variant, language selection is usually not enabled. If you see a similar case, contact Tiqets support.

User and API flow

1. Show Language Selection to your customers

Before displaying any dates, times, or variants, ask the customer to choose their preferred language.
Only allow selection from the languages provided in the API response (language_selection).

2. Retrieve and filter availability by language to show relevant availability to the customer

Once the customer selects a language, call the Availability API.
On the backend, filter out any variants that do not support the selected language.
Return only the dates, and times available in that language.

3. Show Variants That Match the Selected Language

Display only the variants that support the selected language.
Make it clear that the tour will be conducted in the selected language.

3. Booking a Product Based on Language Selection (Booking API)

Unlike other APIs, you do not specify the selected language in the booking request. Instead, the user selects a variant, and that variant determines the language.

Once the customer selects a valid variant, proceed with the booking using the booking by making a POST request to the Tiqets Orders API

POST https://api.tiqets.com/v2/orders

Example of payload

{
  "product_id": 1109115,
  "day": "2025-12-17",
  "variants": [
    {
      "variant_id": 38100,
      "count": 3
    }
  ],
  "customer_details": {
    "firstname": "Fred",
    "lastname": "Bloggs",
    "phone": "5551234",
    "email": "[email protected]"
  }
}

✅ The variant ID automatically determines the language—no need to send a separate language parameter. ✅ The variants array includes the variant_id, ensuring that the booking is tied to a specific language.

3.1 Linking to a Product with Language Selection pre-filled (Affiliate link)

If instead of collecting payment and performing the booking yourself you want to use our Affiliate links structure, you can easily do so by constructing the URL using the following parameters:

Parameter

Description

Example values

selected_variant_language

Pre-selects the language for the product

eng (English), spa (Spanish)

selected_date

Pre-selects the booking date

2025-03-14

selected_timeslot_id

Pre-selects the timeslot

09:30 (09:30 AM)

selected_variants

Pre-selects the specific variant(s)

157961=1&157963=2 _{(Variant ID}₁₅₇₉₆₁_{, Quantity}₁_{and Variant ID}₁₅₇₉₆₃_{, Quantity}₂₎

For a Louvre Museum guided tour in English, pre-selected for March 14, 2025, at 09:30 AM, booking 1 ticket for variant ID 157961:

https://www.tiqets.com/en/things-to-do-in-paris-c66746/tickets-for-louvre-museum-dedicated-entry-guided-tour-p1109115/
    ?selected_variant_language=eng
    &selected_date=2025-03-14
    &selected_timeslot_id=09%3A30
    &selected_variants=157961%3D1%26157963%3D2

✅ The language (eng) is pre-selected, so the user lands on the page with their preferred language. ✅ The date (2025-03-14) and timeslot (09:30 AM) are pre-filled. ✅ The variant (157961=1&157963=2) ensures the correct tour options are chosen.

Make sure to URL encode the values of the selected_timeslot_id and selected_variants parameters.

Testing

The following products can be used in the test environment https://api-tiqt-test.steq.it/v2/product/1006523

Variant ID: 38286 returns eng (English)
Variant ID: 38287 returns fra (French)

Handling Edge Cases & Best Practices

What if the product only supports one language?

If the language_selection field contains only one value, Tiqets recommends still showing the selector, as it may help users understand that the product is limited to that language.

What if the user’s preferred language isn’t available?

If the preferred language is missing, suggest English as an alternative, but we suggest that you allow the user to make the final choice for clarity purposes.

How often does language availability change?

Language availability is included in the availability endpoint but is usually stable and does not require aggressive refresh mechanism.

PreviousSharing essential product information with your customers NextMaximising availability using Multi-sourcing

Last updated 2 months ago

Was this helpful?