---
uuid: 49440062-f009-4947-9f34-a88b59e97bca
date_created: 2026-02-27T06:19:33.397Z
date_updated: 2026-04-03T08:26:30.242Z
seo_url: flexible-search-duration-and-dates
category: Shopping calendar
tags: 
  - Product Information
  - Commercial information
routes: 
  - GET /v1/products/{product_id}/bookable_dates
  - GET /v2/products/{product_id}/calendar
---

# Flexible search (duration and dates)

This scenario documents a flexible search journey that combines bookable dates and calendar inspection to help a user explore durations and date windows before selecting an exact departure.

## Flow

```mermaid
flowchart LR
    step0["Explore bookable dates and durations"]
    step1["Inspect the calendar for selected criteria"]
    step0 --> step1
```

## Overview

The route sequence starts with `GET /v1/products/{product_id}/bookable_dates` to identify eligible dates and durations, then uses `GET /v2/products/{product_id}/calendar` to inspect the pricing calendar for the selected criteria.

## Prerequisites

* `product_id` must be known.
* Date and duration filters may be required depending on the exploration mode.
* `accept-language` and `x-api-key` are required on the documented calls.

## 1 - Explore bookable dates and durations

Use `GET /v1/products/{product_id}/bookable_dates` to discover which departure dates are bookable and which stay durations are available for each date before choosing a precise search context.

#### Prerequisites

* Header `accept-language`
* Header `x-api-key`
* Optional header `authorization`
* Path `product_id`
* Optional query `departure_option_id`
* Optional query `first_date`
* Optional query `last_date`

#### Calling CURL

```bash
curl --get "https://api.clubmed.com/v1/products/MPAC/bookable_dates" \
  -H "accept-language: en-US" \
  -H "x-api-key: <your-api-key>" \
  --data-urlencode "first_date=2022-04-15" \
  --data-urlencode "last_date=2022-06-15"
```

#### Example answer

```json
{
  "months": [
    {
      "id": 202001,
      "days": [
        {
          "id": 20200101,
          "availabilities": [
            {
              "status": "OPEN",
              "sibling_id": "CHAC_SUMMER",
              "durations": [7]
            }
          ]
        }
      ]
    }
  ]
}
```

> **info:** This route is useful when the user is still flexible on both departure date and duration. Reuse the selected day and duration in the price calendar step.

***

**Response codes**

* `200`: bookable dates returned successfully.
* `400`: bad request or validation error.
* `401`: unauthorized when a protected context is requested.
* `404`: unknown product.

**Related route**: [GET https://api.clubmed.com//v1/products/{product\_id}/bookable\_dates](https://api.clubmed.com/doc?search=GET%20%2Fv1%2Fproducts%2F%7Bproduct_id%7D%2Fbookable_dates)

## 2 - Inspect the calendar for selected criteria

Use `GET /v2/products/{product_id}/calendar` once the user has narrowed down the duration and traveller criteria returned by the flexible exploration step.

#### Prerequisites

* Header `accept-language`
* Header `x-api-key`
* Optional header `authorization`
* Path `product_id`
* Required query `duration`
* Optional query `departure_option_id`
* Optional query `number_attendees`
* Optional query `birthdates`
* Optional query `first_date`
* Optional query `last_date`

#### Calling CURL

```bash
curl --get "https://api.clubmed.com/v2/products/MPAC/calendar" \
  -H "accept-language: en-US" \
  -H "x-api-key: <your-api-key>" \
  --data-urlencode "duration=7" \
  --data-urlencode "number_attendees=2" \
  --data-urlencode "first_date=2022-04-15" \
  --data-urlencode "last_date=2022-06-15"
```

#### Example answer

```json
{
  "months": [
    {
      "id": "201511",
      "days": [
        {
          "id": "20151129",
          "availability": "OPEN",
          "price": {
            "currency": "EUR"
          },
          "terms_and_conditions": {
            "duration": 7,
            "package": "AI",
            "departure_city": {
              "id": "PAR",
              "label": "Paris"
            }
          }
        }
      ]
    }
  ]
}
```

> **info:** This step turns a flexible search into a price comparison view. Use the returned days to decide which departure date should feed the next proposal or booking step.

***

**Response codes**

* `200`: calendar returned successfully.
* `400`: missing `duration`, bad request or validation error.
* `401`: unauthorized when a protected context is requested.
* `404`: unknown product.

**Related route**: [GET https://api.clubmed.com//v2/products/{product\_id}/calendar](https://api.clubmed.com/doc?search=GET%20%2Fv2%2Fproducts%2F%7Bproduct_id%7D%2Fcalendar)