Booking path with services and attendees

  • Booking
  • 4 routes
How do I prepare a proposal with services before turning it into a booking?

This scenario documents the preparation phase of a booking journey, from proposal creation to service review and attendee qualification. It fits booking flows that must secure a proposal before the final booking creation.

The flow creates a proposal, lists the available and already attached services, and then updates attendee information so the proposal is ready for the next step of the booking journey.

Overview

This scenario helps an application prepare a proposal with the right service context and attendee data before the booking is created.

Prerequisites

  • The booking criteria required to create the proposal.
  • A valid x-api-key and an authorization context when the route requires one.
  • A proposal_id returned by the creation step to continue the flow.

Expected result

The application can create a working proposal, inspect the service context, and complete attendee data so the file is ready for booking creation or pricing validation.

Process workflow

Legend:
Mandatory
Optional
1

Search matching proposals

Mandatory

Use POST/v3/proposals/search to generate the proposal that will serve as the booking working file. This route calculates price, availability, option duration, and the first traveler structure from the submitted booking criteria.

Prerequisites

  • Send accept-language and x-api-key.
  • Add authorization when the context requires it.
  • Prepare a complete booking payload with product, dates, attendee count, and package context.

Calling CURL

curl -X 'POST' \
  'https://api.clubmed.com/v3/proposals/search' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Example answer

{
  "id": "123456",
  "product_id": "MPAC",
  "price": {
    "total": 9815.4,
    "currency": "EUR"
  },
  "remaining_stock": 2,
  "option_available": true
}

info: Keep the returned proposal_id and the pricing block. They become the reference for all later service, attendee, or booking steps.

Response codes

  • 200 OK: returns the proposal matching the submitted criteria.
  • 400 Bad Request: the payload is invalid, incomplete, or inconsistent.
  • 401 Unauthorized: authentication is missing, invalid, or expired.
  • 403 Forbidden: the current context is not allowed to create the proposal.
  • 404 Not Found: the product cannot be found.
  • 409 Conflict: the proposal criteria are no longer valid.
POST/v3/proposals/search
See more
2

List the additional services available for the proposal

Optional

Use GET/v0/additional_services with proposal_id to list the additional services that can be attached to the current proposal. This includes childcare, transfer, insurance, rental, excursion, and other service families when they are available for the selected stay.

Prerequisites

  • Reuse a valid proposal_id.
  • Send accept-language and x-api-key.
  • Optionally filter the result with types when you only want a specific family of services.

Calling CURL

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

Example answer

[
  {
    "id": "VMOSK1",
    "type": "CHILDCARE",
    "currency": "EUR",
    "schedules": [
      {
        "start_date": "20100430",
        "end_date": "20100430",
        "remaining_stock": 2
      }
    ]
  }
]

info: Use this route to discover what can be sold. The next service step should only reuse identifiers returned here.

Response codes

  • 200 OK: returns the services available for the proposal.
  • 206 Partial Content: the result is partial and may require pagination.
  • 400 Bad Request: the proposal or request filters are invalid.
  • 401 Unauthorized: authentication is missing, invalid, or expired.
  • 403 Forbidden: the current market or authentication does not allow this lookup.
  • 404 Not Found: the proposal cannot be found.
  • 409 Conflict: the proposal criteria are no longer valid.
  • 416 Requested Range Not Satisfiable: the requested range is invalid.
GET/v0/additional_services
See more
3

Review the services already attached to the proposal

Optional

Use GET/v0/proposals/{proposal_id}/services to review the additional services already attached to the proposal. This step is useful after a service-selection UI or before attendee qualification to confirm what is already in the file.

Prerequisites

  • Provide proposal_id.
  • Send x-api-key.
  • Optionally add a filter to narrow the response.

Calling CURL

curl -X 'GET' \
  'https://api.clubmed.com/v0/proposals/123456/services' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

Example answer

[
  {
    "id": "AHSI01",
    "type": "RENTAL",
    "currency": "EUR",
    "schedules": [
      {
        "start_date": "20100430",
        "end_date": "20100430",
        "attendees": [
          {
            "id": "A",
            "price": 250
          }
        ]
      }
    ]
  }
]

info: This route reflects the current proposal state. Use it to confirm which services were kept after a cancel-and-replace update.

Response codes

  • 200 OK: returns the services currently attached to the proposal.
  • 400 Bad Request: the request or the filter is invalid.
GET/v0/proposals/{proposal_id}/services
See more
4

Qualify the proposal attendees

Optional

Use PUT/v3/proposals/{proposal_id}/attendees to attach or update attendee data on the proposal before booking creation. This is where names, identities, and customer links are secured so the proposal can move toward booking.

Prerequisites

  • Provide proposal_id.
  • Send accept-language, authorization when required, and x-api-key.
  • Prepare an attendee payload that respects the documented constraints on birthdates, documents, and household composition.

Calling CURL

curl -X 'PUT' \
  'https://api.clubmed.com/v3/proposals/123456/attendees' \
  -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

[
  {
    "attendees": [
      {
        "id": "A",
        "customer_id": "123456789",
        "customer_status": "NEW_CUSTOMER",
        "loyalty_status": "GOLD"
      }
    ]
  }
]

info: This is the gatekeeping step before booking creation. Most validation errors on identity, documents, and household consistency surface here.

Response codes

  • 200 OK: returns the updated attendee structure.
  • 400 Bad Request: attendee data is invalid, incomplete, duplicated, or inconsistent.
  • 401 Unauthorized: authentication is missing, invalid, or expired.
  • 403 Forbidden: at least one customer is not allowed to continue.
  • 409 Conflict: the proposal is no longer economically valid.
PUT/v3/proposals/{proposal_id}/attendees
See more