List and inspect a customer's bookings

  • Bookings
  • Booking
  • 2 routes
How do I list a customer's bookings and open one in detail?

This scenario explains how to list the bookings attached to a customer account and then open the details of one selected booking. It supports customer selfcare, advisor tools and follow-up journeys that need both a portfolio view and a drill-down on a specific file.

The flow starts with the bookings collection for a known customer_id, optionally filtered by period, booking status or booking type, then uses the returned booking_id to open the full booking detail.

Overview

This scenario is designed for applications that need to display a customer's booking portfolio and then inspect a selected booking in detail.

Prerequisites

  • A valid bearer token, x-api-key and accept-language header.
  • A known customer_id.
  • A booking_id returned by the list step to access the detailed view.

Expected result

The application can display the customer's bookings, apply the available list filters and open the full detail of a selected booking.

Process workflow

Legend:
Mandatory
Optional
1

List customer bookings

Mandatory

Use GET/v3/customers/{customer_id}/bookings to list the bookings attached to one customer account before opening one booking in detail.

Prerequisites

  • Have a valid customer_id.
  • Send accept-language, authorization, and x-api-key.
  • Prepare filters such as period, booking_status, min_creation_date, sort, page, and limit when you need to narrow the result set.

Calling CURL

curl -X 'GET' \
  'https://api.clubmed.com/v3/customers/123456789/bookings?period=CURRENTS&booking_status=VALIDATED,OPTION&min_creation_date=2025-01-01&sort=-creation_date&page=1&limit=10' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'x-api-key: YOUR_API_KEY'

Example answer

[
  {
    "id": "12345",
    "booking_status": "VALIDATED",
    "payment_status": "PAID",
    "locale": "fr-FR",
    "allowed_to_pay": true,
    "option_durability": {
      "expiration_date_time": "2026-04-03T18:00:00Z",
      "is_reliable": true
    },
    "total_price": {
      "amount": 9815.4,
      "currency": "EUR"
    },
    "stays": [
      {
        "id": "AGAC20160415",
        "product_id": "AGAC",
        "label": "Agadir",
        "resort_arrival_date": "20160415",
        "duration": 7
      }
    ]
  }
]

info: the period filter is based on the booking dates, while min_creation_date and sort help you narrow the list for customer-service and seller journeys.

Response codes

  • OK Response (200): returns the list of bookings that match the requested customer and filters.
  • Error (400): one filter or input value is invalid.
  • Error (401): authentication is missing, invalid, or expired.
  • Error (403): access is forbidden because of a customer, issuer, or locale mismatch.
  • Error (404): not documented in Swagger.
  • Error (416): the requested page range is not satisfiable.
GET/v3/customers/{customer_id}/bookings
See more
2

Consult booking details

Mandatory

Use GET/v3/customers/{customer_id}/bookings/{booking_id} to retrieve the detailed content of one booking returned by the previous list step.

Prerequisites

  • Reuse the customer_id and one booking_id returned by the list step.
  • Send accept-language, authorization, and x-api-key.
  • Call this step after selecting the exact booking to inspect.

Calling CURL

curl -X 'GET' \
  'https://api.clubmed.com/v3/customers/123456789/bookings/0123456789' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'x-api-key: YOUR_API_KEY'

Example answer

{
  "id": "12345",
  "booking_status": "VALIDATED",
  "payment_status": "PAID",
  "allowed_to_pay": true,
  "booking_renewal": true,
  "option_durability": {
    "expiration_date_time": "2026-04-03T18:00:00Z",
    "is_reliable": true
  },
  "total_price": {
    "amount": 9815.4,
    "currency": "EUR"
  },
  "stays": [
    {
      "id": "AGAC20160415",
      "product_id": "AGAC",
      "label": "Agadir",
      "resort_arrival_date": "20160415",
      "duration": 7
    }
  ],
  "easy_arrival": {
    "status": "AVAILABLE"
  }
}

info: v3 exposes payment and option-control fields directly on the booking payload, which makes it easier to drive detail screens and payment actions from a single response.

Response codes

  • OK Response (200): returns the detailed booking content for the selected customer and booking.
  • Error (400): one input value is invalid.
  • Error (401): authentication is missing, invalid, or expired.
  • Error (403): access is forbidden because of a customer, issuer, or locale mismatch.
  • Error (404): the booking_id was not found for the given customer.
GET/v3/customers/{customer_id}/bookings/{booking_id}
See more