Skip to main content

​
Overview

Cancels an existing booking. The cancellation behavior depends on your partner account’s paymentResponsibility:
  • CLEANOS responsibility: The system cancels the booking and issues a refund if applicable.
  • PARTNER responsibility: The system cancels the booking only — no refund is processed by CleanLife. Your system is responsible for any refund to your customer.

​
Endpoint

PATCH /partners/bookings/:bookingId/cancel

​
Authentication

Requires a valid API Key with the partner_bookings_cancel permission.

​
Path Parameters

ParameterTypeRequiredDescription
bookingIdUUIDYesThe booking ID returned at creation time.

​
Request Body

{
  "reasonId": "aaaaaaaa-0000-0000-0000-000000000001",
  "notes": "Customer requested cancellation."
}
FieldTypeRequiredDescription
reasonIdUUIDNoID of a predefined cancellation reason from the CleanLife catalog. If omitted, no reason is recorded.
notesstringNoFree-text notes about the cancellation.

​
Example Request

curl -X PATCH "https://apiv3.thecleanlife.dev/v1/partners/bookings/11111111-0000-0000-0000-000000000001/cancel" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Customer requested reschedule to a later date."
  }'

​
Success Response

HTTP Status: 200 OK 
{
  "success": true,
  "data": {
    "bookingId": "11111111-0000-0000-0000-000000000001",
    "externalReference": "ORDER-20260615-001",
    "appointmentId": "22222222-0000-0000-0000-000000000002",
    "status": "canceled",
    "paymentStatus": "CANCELLED",
    "trackingReference": "SA-0042",
    "date": "2026-06-20T00:00:00.000Z",
    "timeslot": {
      "startAt": "09:00",
      "endAt": "12:00",
      "endsAtNextDay": false
    },
    "appointment": {
      "id": "22222222-0000-0000-0000-000000000002",
      "name": "SA-0042",
      "status": "Cancelled",
      "scheduledStartDateTime": "2026-06-20T09:00:00+03:00",
      "scheduledEndDateTime": "2026-06-20T12:00:00+03:00"
    }
  }
}

​
Error Responses

HTTP StatusCodeDescription
400VALIDATION_ERRORInvalid path or body parameter
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENMissing partner_bookings_cancel permission
404RESOURCE_NOT_FOUNDBooking not found or does not belong to your partner account
422BOOKING_ALREADY_CANCELLEDBooking is already in canceled status

​
Business Rules

  1. Cannot cancel an already-cancelled booking. If the booking is already in canceled status, the API returns 422 BOOKING_ALREADY_CANCELLED. You can safely check for this error and treat it as a successful no-op.
  2. Refund behavior:
    • CLEANOS responsibility: The service appointment is cancelled with action CANCEL_AND_REFUND. The CleanLife system will initiate a refund if applicable.
    • PARTNER responsibility: The service appointment is cancelled with action CANCEL_ONLY. No refund is initiated by CleanLife.
  3. Webhook on cancellation. A booking.cancelled webhook event is sent after successful cancellation.

​
Notes

  • There is no restriction on which booking statuses can be cancelled via this endpoint (other than already-cancelled bookings). You can cancel a booking in waiting payment, in progress, or success status.
  • If you need to cancel and then rebook for a different date, cancel the existing booking and create a new one.
  • GET /partners/bookings/:bookingId/status — Verify booking status before cancelling
  • POST /partners/bookings — Create a replacement booking