Book a spa

Services
Booking upsell
5 routes

How to let a customer browse, book, and cancel a spa appointment from a booking?

This scenario documents how a customer can browse spa information, inspect care availability, review existing appointments, book a spa slot, and cancel it when needed from a booking context.

Overview

The route sequence combines product-level spa discovery with customer booking actions. It helps build a complete spa booking journey from care selection to appointment cancellation.

Prerequisites

product_id is needed to list spas and cares.
customer_id and booking_id are required for customer booking actions.
Customer-scoped routes require authorization, and all documented calls require accept-language and x-api-key.

Process workflow

Legend:

Mandatory

Optional

Retrieve spa information

Mandatory

Use GET/v0/products/{product_id}/spas to retrieve the spa metadata exposed for a product, including the spa identity, contact details, cancellation limit and the list of available cares.

Prerequisites

Header accept-language
Header x-api-key
Path product_id

Calling CURL

curl -X GET "https://api.clubmed.com/v0/products/MPAC/spas" \
  -H "accept-language: en-US" \
  -H "x-api-key: <your-api-key>"

Example answer

{
  "id": 432423,
  "label": "Aginum Thermae",
  "currency": "EUR",
  "location": "Location",
  "are_children_accepted": true,
  "cancellation_hours_limit": 24,
  "cares": [
    {
      "id": 432423,
      "label": "Anti-Aging",
      "sub_category": "Anti-aging",
      "duration": 60,
      "total_duration": 75,
      "price": {
        "value": 44,
        "currency": "EUR"
      }
    }
  ]
}

info: Reuse the returned care identifiers in the availability step. The spa-level metadata is also useful to display contact information and cancellation rules before booking.

Response codes

200: spa information returned successfully.
400: bad request or validation error.
404: unknown product or no spa exposed for the targeted product.

GET/v0/products/{product_id}/spas

Check treatment availabilities

Mandatory

Use GET/v0/products/{product_id}/spas/cares/{care_code} to retrieve the available time slots for one care in the selected product.

Prerequisites

Header accept-language
Header x-api-key
Path product_id
Path care_code
Optional query date_format
Optional query start_date
Optional query end_date

Calling CURL

curl -X GET "https://api.clubmed.com/v0/products/MPAC/spas/cares/3922446?start_date=2022-04-15T10:23:00.234Z&end_date=2022-04-16T10:23:00.234Z&date_format=ISO" \
  -H "accept-language: en-US" \
  -H "x-api-key: <your-api-key>"

Example answer

[
  {
    "start_date_time": "2022-04-15T10:23:00.234Z",
    "end_date_time": "2022-04-15T10:23:00.234Z",
    "employees": [
      {
        "id": 432423,
        "name": "Thomas",
        "gender": "MALE"
      }
    ]
  }
]

info: Use this response to let the customer choose a slot and, when relevant, a practitioner before creating the appointment.

Response codes

200: availabilities returned successfully.
400: invalid date range, invalid care code, bad request or validation error.
404: unknown product or inaccessible care for the targeted product.

GET/v0/products/{product_id}/spas/cares/{care_code}

Retrieve existing spa appointments

Optional

Use GET/v0/customers/{customer_id}/bookings/{booking_id}/spas to list the spa appointments already linked to a booking before adding or cancelling one.

Prerequisites

Header authorization
Header accept-language
Header x-api-key
Path customer_id
Path booking_id
Required query product_id
Optional query date_format

Calling CURL

curl -X GET "https://api.clubmed.com/v0/customers/123456789/bookings/0123456789/spas?product_id=MPAC&date_format=ISO" \
  -H "authorization: Bearer <token>" \
  -H "accept-language: en-US" \
  -H "x-api-key: <your-api-key>"

Example answer

[
  {
    "booking_number": "100565795179",
    "appointment_id": 565795179,
    "order_id": 710834209,
    "status": "Confirmed",
    "start_date_time": "2022-04-15T10:23:00.234Z",
    "end_date_time": "2022-04-15T10:23:00.234Z",
    "price": {
      "value": 105,
      "currency": "EUR"
    },
    "spa_care": {
      "id": 432423,
      "label": "Anti-Aging"
    }
  }
]

info: The response gives you the appointment identifiers required to cancel an existing booking and helps avoid duplicate reservations on the same booking.

Response codes

200: existing spa appointments returned successfully.
400: missing product_id, bad request or validation error.
401: unauthorized.
404: booking not found for the targeted customer.

GET/v0/customers/{customer_id}/bookings/{booking_id}/spas

Book the spa appointment

Mandatory

Use POST/v0/customers/{customer_id}/bookings/{booking_id}/spas to create a spa appointment for a selected booking and customer.

Prerequisites

Header authorization
Header accept-language
Header x-api-key
Path customer_id
Path booking_id
The route expects a request body. The exact full schema is not visible in the available contract excerpt, but it must carry the selected slot and booking context.

Calling CURL

curl -X POST "https://api.clubmed.com/v0/customers/123456789/bookings/0123456789/spas" \
  -H "authorization: Bearer <token>" \
  -H "accept-language: en-US" \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json"

Example answer

{
  "booking_number": "100565795179",
  "appointment_id": 565795179,
  "order_id": 710834209,
  "status": "Confirmed",
  "price": {
    "value": 105,
    "currency": "EUR"
  },
  "upsells": [
    {
      "id": 432423,
      "label": "Anti-Aging",
      "type": "AFTER"
    }
  ]
}

info: Save the returned appointment_id immediately if your channel supports later cancellation or booking recap pages.

Response codes

200: appointment created successfully.
400: bad request, validation error or invalid JSON payload.
401: unauthorized.
404: booking not found for the targeted customer.
409: a booking request already exists for the same criteria.

POST/v0/customers/{customer_id}/bookings/{booking_id}/spas

Cancel a spa appointment

Optional

Use DELETE /v0/customers/{customer_id}/bookings/{booking_id}/spas/{appointment_id} to cancel a previously booked spa appointment.

Prerequisites

Header authorization
Header accept-language
Header x-api-key
Path customer_id
Path booking_id
Path appointment_id

Calling CURL

curl -X DELETE "https://api.clubmed.com/v0/customers/123456789/bookings/0123456789/spas/565795179" \
  -H "authorization: Bearer <token>" \
  -H "accept-language: en-US" \
  -H "x-api-key: <your-api-key>"

Example answer

HTTP/1.1 204 No Content

info: No response body is returned on success. Keep the original appointment identifier from the retrieval or booking step to target the correct appointment.

Response codes

204: appointment cancelled successfully.
400: bad request or validation error.
401: unauthorized.
404: booking or appointment not found for the targeted customer.

DELETE/v0/customers/{customer_id}/bookings/{booking_id}/spas/{appointment_id}