Add insurance to a booking

  • Services
  • 3 routes
How do I list available insurances and add one to an existing booking?

This scenario explains how to retrieve an existing booking, list the insurances available for it, and add the insurance service to the booking cart. It fits assisted-sales, customer-service, and booking-finalization journeys that require additional coverage.

The flow relies on a known customer_id and booking_id, then chains insurance discovery and service addition into the cart.

Overview

This scenario helps an application propose insurance on an already created booking without restarting from proposal search.

Prerequisites

  • Valid customer_id and booking_id values.
  • An authentication context and the headers required by the routes in the flow.
  • An insurance product compatible with the booking and target market.

Expected result

The application can display the available insurances and add the selected insurance to the booking cart so the journey can continue toward confirmation.

Process workflow

Legend:
Mandatory
Optional
1

List bookings eligible for insurance upsell

Mandatory

This route returns the bookings accessible in the current context. Use it to identify the target booking_id before listing insurances and adding the selected one to the booking cart.

Prerequisites

  • Send accept-language and x-api-key.
  • Add authorization when the context requires an authenticated customer or seller.
  • Reuse filters such as customer_id, booking_status, or payment_status to narrow the booking list.

Calling CURL

curl -X 'GET' \
  'https://api.clubmed.com/v2/bookings?customer_id=123456789&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",
    "products": [
      {
        "id": "ALHC_WINTER",
        "label": "ALPES HUEZ",
        "type": "VILLAGE"
      }
    ],
    "option_durability": {
      "expiration_date_time": "20160415T10:23:00.234Z",
      "is_reliable": true
    }
  }
]

info: Reuse the returned booking_id to target the correct booking in the insurance-cart step.

Response codes

  • OK Response (200): returns the bookings matching the submitted filters.
  • Error (206): the response is partial and more pages may still be available.
  • Error (400): filters, sorting, or pagination parameters are invalid.
  • Error (401): authentication is missing, invalid, or expired.
  • Error (404): non documented in Swagger.
GET/v2/bookings
See more
2

List the available insurance services

Mandatory

Use GET/v0/insurances to retrieve the insurance catalog available in the current commercial context. This step lets you compare the available products, insurers, and coverage labels before selecting the insurance to add to the booking.

Prerequisites

  • Send accept-language and x-api-key.
  • Reuse the booking or product context already identified in the previous step.
  • Keep the selected market and locale consistent with the booking journey.

Calling CURL

curl -X 'GET' \
  'https://api.clubmed.com/v0/insurances' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'x-api-key: YOUR_API_KEY'

Example answer

[
  {
    "id": "TRAVEL_INSURANCE",
    "label": "Travel Insurance",
    "description": "Coverage for cancellation and assistance",
    "company": {
      "label": "Club Med Insurance Partner"
    },
    "coverage_descriptions": [
      "Cancellation",
      "Medical assistance"
    ]
  }
]

info: Keep the returned insurance identifier and the main coverage labels so the user can make a clear choice before the add-to-cart step.

Response codes

  • 200 OK: returns the list of insurances available in the current context.
  • 400 Bad Request: the request or one filter is invalid.
  • 403 Forbidden: access to the insurance catalog is forbidden in the current context.
  • 404 Not Found: no insurance is available for the requested context.
GET/v0/insurances
See more
3

Add the insurance to the booking cart

Mandatory

Use POST/v1/customers/{customer_id}/bookings/{booking_id}/cart/services to add the selected insurance or service to an existing booking cart. Trigger this step only after the target booking_id and the insurance identifier are both known.

Prerequisites

  • Provide customer_id and booking_id.
  • Send accept-language, authorization, and x-api-key.
  • Prepare a payload aligned with the selected service. The exact request-body structure is not fully exposed in the Swagger excerpt.

Calling CURL

curl -X 'POST' \
  'https://api.clubmed.com/v1/customers/123456789/bookings/12345/cart/services' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Example answer

HTTP/1.1 204 No Content

info: Swagger documents this step as a success without response body. If you later need to remove the insurance, use the dedicated cart-removal route.

Response codes

  • 204 No Content: the selected service has been added to the booking cart.
  • 400 Bad Request: the payload or the booking context is invalid.
  • 401 Unauthorized: authentication is missing, invalid, or expired.
  • 403 Forbidden: the current context is not allowed to add this service.
  • 501 Not Implemented: the documented upsell flow is not available for some booking configurations.
POST/v1/customers/{customer_id}/bookings/{booking_id}/cart/services
See more