# How to implement language selection

### Introduction <a href="#introdction" id="introdction"></a>

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 href="#why-show-a-language-selector" id="why-show-a-language-selector"></a>

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.<br>

### **1. Checking Available Languages for a Product** <a href="#id-1.-checking-available-languages-for-a-product" id="id-1.-checking-available-languages-for-a-product"></a>

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:**

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

&#x20;

* 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](http://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..<br>

{% hint style="warning" %}

## Other language related fields

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](/basics/openapi.md).
{% endhint %}

### **2. Checking which Languages are Available for Specific Variants** <a href="#id-2.-checking-which-languages-are-available-for-specific-variants" id="id-2.-checking-which-languages-are-available-for-specific-variants"></a>

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:**

```json
{
    "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 <a href="#user-and-api-flow" id="user-and-api-flow"></a>

**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`).

<figure><img src="/files/cDTuiQLZ0YwVwLmNwti5" alt=""><figcaption></figcaption></figure>

#### 2. Retrieve and filter availability by language to show relevant availability to the customer <a href="#id-2.-retrieve-and-filter-availability-by-language-to-show-relevant-availabilities-to-the-customer" id="id-2.-retrieve-and-filter-availability-by-language-to-show-relevant-availabilities-to-the-customer"></a>

* 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.

<figure><img src="/files/cQ9JUd0g7ZzD849bK0FQ" alt=""><figcaption></figcaption></figure>

#### 3. Show Variants That Match the Selected Language <a href="#id-3.-show-variants-that-match-the-selected-language" id="id-3.-show-variants-that-match-the-selected-language"></a>

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

<figure><img src="/files/WlF4PF3bKNmisFIinkZt" alt=""><figcaption></figcaption></figure>

### **3. Booking a Product Based on Language Selection (Booking API)** <a href="#id-5.-booking-a-product-based-on-language-selection-booking-api" id="id-5.-booking-a-product-based-on-language-selection-booking-api"></a>

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`&#x20;

**Example of payload**

```json
{
  "product_id": 1109115,
  "day": "2025-12-17",
  "variants": [
    {
      "variant_id": 38100,
      "count": 3
    }
  ],
  "customer_details": {
    "firstname": "Fred",
    "lastname": "Bloggs",
    "phone": "5551234",
    "email": "fred.bloggs@example.com"
  }
}
```

✅ 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)** <a href="#id-5.1-linking-to-a-product-with-language-selection-pre-filled-affiliate-link" id="id-5.1-linking-to-a-product-with-language-selection-pre-filled-affiliate-link"></a>

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)      | <p><code>157961=1&157963=2</code> <br><sub>(Variant ID <code>157961</code>, Quantity <code>1</code> and Variant ID <code>157963</code>, Quantity <code>2</code>)</sub></p> |

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 <a href="#how-to-test-for-booking-api" id="how-to-test-for-booking-api"></a>

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?** <a href="#what-if-the-product-only-supports-one-language" id="what-if-the-product-only-supports-one-language"></a>

* 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?** <a href="#what-if-the-users-preferred-language-isnt-available" id="what-if-the-users-preferred-language-isnt-available"></a>

* 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?** <a href="#how-often-does-language-availability-change" id="how-often-does-language-availability-change"></a>

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

\ <br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.tiqets.dev/integration-guides/product-integration/how-to-implement-language-selection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.