Skip to main content

​
Overview

Partially updates an existing booking. You can reschedule the booking to a new date and/or timeslot, add notes, or update your externalReference.
Only bookings in in progress or waiting payment status can be updated. Attempting to update a booking in any other status will return a 422 error.

​
Endpoint

PATCH /partners/bookings/:bookingId

​
Authentication

Requires a valid API Key with the partner_bookings_update permission.

​
Path Parameters

ParameterTypeRequiredDescription
bookingIdUUIDYesThe booking ID returned at creation time.

​
Request Body

All fields are optional. Only include the fields you want to change. 
{
  "date": "2026-06-25",
  "timeslot": {
    "startAt": "10:00",
    "endAt": "13:00"
  },
  "notes": "Customer prefers the team to arrive exactly on time.",
  "externalReference": "ORDER-20260615-001-V2"
}
FieldTypeRequiredDescription
dateISO date stringNoNew service date (YYYY-MM-DD in Riyadh local time).
timeslotobjectNoNew timeslot. If provided, both startAt and endAt should be included.
timeslot.startAtstringNoNew start time (HH:MM or HH:MM:SS).
timeslot.endAtstringNoNew end time (HH:MM or HH:MM:SS).
notesstringNoFree-text notes about the booking.
externalReferencestringNoUpdates your external reference. Must be unique within your partner account. Max 150 characters.

​
Example Request

curl -X PATCH "https://apiv3.thecleanlife.dev/v1/partners/bookings/11111111-0000-0000-0000-000000000001" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-06-25",
    "timeslot": {
      "startAt": "10:00",
      "endAt": "13:00"
    }
  }'

​
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": "in progress",
    "paymentStatus": "NOT_REQUIRED",
    "trackingReference": "SA-0042",
    "date": "2026-06-25T00:00:00.000Z",
    "timeslot": {
      "startAt": "10:00",
      "endAt": "13:00",
      "endsAtNextDay": false
    },
    "appointment": {
      "id": "22222222-0000-0000-0000-000000000002",
      "name": "SA-0042",
      "status": "Scheduled",
      "scheduledStartDateTime": "2026-06-25T10:00:00+03:00",
      "scheduledEndDateTime": "2026-06-25T13:00:00+03:00"
    }
  }
}

​
Error Responses

HTTP StatusCodeDescription
400VALIDATION_ERRORInvalid field values
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENMissing partner_bookings_update permission
404RESOURCE_NOT_FOUNDBooking not found or does not belong to your partner account
409DUPLICATE_EXTERNAL_REFERENCEThe new externalReference is already used by another booking
422BOOKING_NOT_EDITABLEBooking status is not in progress or waiting payment
422BOOKING_APPOINTMENT_NOT_FOUNDCannot reschedule — no service appointment exists

​
Business Rules

  1. Status restriction. Only bookings in in progress or waiting payment can be updated. Completed, cancelled, and failed bookings are immutable.
  2. Rescheduling. If you provide a new date or timeslot, the linked service appointment is updated with the new schedule.
  3. Partial timeslot update. If you provide only date without timeslot (or vice versa), the existing values are preserved. For example, providing only a new date keeps the existing startAt/endAt times.
  4. Overnight bookings. The endsAtNextDay flag is preserved from the original booking during rescheduling.
  5. externalReference upsert. If the booking did not have an externalReference at creation time, providing one in an update will associate it. If a reference already exists, it is updated (subject to uniqueness).
  6. Webhook on update. A booking.updated webhook event is fired after a successful update.

​
Notes

  • The notes field is saved on the booking but is not returned in the API response.
  • Verifying timeslot availability before rescheduling is recommended to avoid scheduling conflicts.
  • GET /partners/bookings/:bookingId/status — Verify current booking status before updating
  • GET /partners/timeslots/available — Check available slots for the new date
  • PATCH /partners/bookings/:bookingId/cancel — Cancel the booking