Create Booking

​

Overview

• CLEANOS responsibility: CleanLife handles payment. Depending on the service price and any coupons applied, the booking may transition to waiting payment (CleanLife sends a payment link asynchronously) or directly to in progress (free service or coupon covers the cost).
• PARTNER responsibility: Your system handles payment. The booking is set to in progress immediately, bypassing CleanLife payment processing. You are expected to confirm payment later via POST /partners/bookings/:bookingId/confirm-payment.

​

Endpoint

POST /partners/bookings

​

Authentication

​

Request Headers

​

Request Body

{
  "externalReference": "ORDER-12345",
  "contactId": "00000000-0000-0000-0000-000000000001",
  "addressId": "00000000-0000-0000-0000-000000000002",
  "serviceId": "00000000-0000-0000-0000-000000000004",
  "packageId": null,
  "customServices": [
    { "id": "00000000-0000-0000-0000-000000000005", "quantity": 2 }
  ],
  "hours": 3,
  "date": "2026-06-20",
  "timeslot": {
    "startAt": "09:00",
    "endAt": "12:00"
  },
  "numberOfTeams": 1,
  "workType": "REGULAR",
  "promoCode": null,
  "contractCode": null,
  "discountCode": null,
  "couponIds": [],
  "codes": [],
  "userId": null
}

​

Field Reference

​

Example Request

curl -X POST "https://apiv3.thecleanlife.dev/v1/partners/bookings" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalReference": "ORDER-20260615-001",
    "contactId": "aaaaaaaa-0000-0000-0000-000000000001",
    "addressId": "bbbbbbbb-0000-0000-0000-000000000002",
    "serviceId": "dddddddd-0000-0000-0000-000000000004",
    "hours": 3,
    "date": "2026-06-20",
    "timeslot": {
      "startAt": "09:00",
      "endAt": "12:00"
    }
  }'

​

Success Response

{
  "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-20T00:00:00.000Z",
    "timeslot": {
      "startAt": "09:00",
      "endAt": "12:00",
      "endsAtNextDay": false
    },
    "appointment": {
      "id": "22222222-0000-0000-0000-000000000002",
      "name": "SA-0042",
      "status": "Scheduled",
      "scheduledStartDateTime": "2026-06-20T09:00:00+03:00",
      "scheduledEndDateTime": "2026-06-20T12:00:00+03:00"
    }
  }
}

​

Response Fields

​

Booking Statuses

​

Payment Statuses

​

Appointment Statuses

​

Error Responses

​

Business Rules

1. externalReference uniqueness: If you provide an externalReference, it must be unique across all bookings for your partner account. Duplicate values result in a 409 error. This is your primary tool for preventing duplicate bookings — generate a unique ID on your side before calling the API.
2. serviceId is required. Choose a serviceId from GET /partners/services. Do not send categoryId — the platform resolves the service category automatically.
3. Timeslot interpretation. All timeslot times (startAt, endAt) are interpreted as Asia/Riyadh local time (UTC+3).
4. Payment flow — CLEANOS responsibility:
   • If the booking total is zero (free service or full coupon), it goes directly to in progress.
   • If the booking requires payment, CleanLife sends a payment link asynchronously. The booking enters waiting payment. A booking.payment_failed webhook is sent if the async payment link fails.
5. Payment flow — PARTNER responsibility:
   • The booking is immediately set to in progress.
   • You must call POST /partners/bookings/:bookingId/confirm-payment once you collect payment from your customer.
6. Failed reference save. In the rare event that a booking is created but the partner reference cannot be saved, the booking is marked as FAILED so you can safely retry with the same externalReference.
7. Webhook on creation. A booking.created webhook event is fired immediately after successful booking creation.

​

Notes

• The appointmentId may be null immediately after creation in some scheduling flows. Monitor the booking.appointment_status_changed webhook event.
• The trackingReference is the value you should display to your customers for tracking purposes.
• Do not rely on the appointment object being present at creation time.

​

Integration Tips

• Always use externalReference to tie CleanLife bookings back to your internal orders. Without it, deduplication on retry is much harder.
• Obtain contactId first via POST /partners/contacts before creating a booking.
• Verify available timeslots first using GET /partners/timeslots/available before creating a booking.
• Calculate the expected price first using POST /partners/pricing/calculate-price to avoid surprises.

​

Common Mistakes

​

Related Endpoints

• POST /partners/contacts — Get or create contactId
• GET /partners/timeslots/available — Get available timeslots before booking
• POST /partners/pricing/calculate-price — Preview the booking price
• GET /partners/bookings/:bookingId/status — Poll booking status
• PATCH /partners/bookings/:bookingId — Update the booking date/timeslot
• PATCH /partners/bookings/:bookingId/cancel — Cancel the booking
• POST /partners/bookings/:bookingId/confirm-payment — Confirm payment (PARTNER responsibility only)