Changelog

All notable changes to the Partner API are documented in this file. The format follows Keep a Changelog.

---

​

[Unreleased]

​

Added

• Contacts API
  • POST /partners/contacts — Find existing contact by phone or create a new one; returns contactId for booking
  • GET /partners/contacts/:contactId — Retrieve a contact by UUID
  • New permission: partner_contacts_read

​

Changed

• Service Catalog — GET /partners/services now returns only services enabled for your partner account
• Create Booking — serviceId is now required; categoryId is resolved automatically from the service and must not be sent
• Create Booking — Removed partner-facing fields: tapId, paymentRedirectUrl, paymentId

​

Planned

• Re-enable Idempotency-Key header support on POST /partners/bookings
• Sandbox environment activation for partner testing

---

​

[1.0.0] — 2026-06-16

​

Added

• Bookings API
  • POST /partners/bookings — Create booking with full payment responsibility support (CLEANOS and PARTNER modes)
  • GET /partners/bookings — List bookings with pagination, filtering by status, date range, and externalReference
  • GET /partners/bookings/:bookingId/status — Get booking status and appointment details
  • PATCH /partners/bookings/:bookingId — Update booking date, timeslot, notes, and externalReference
  • PATCH /partners/bookings/:bookingId/cancel — Cancel booking with refund-or-cancel-only logic based on payment responsibility
  • POST /partners/bookings/:bookingId/confirm-payment — Confirm partner-side payment (PARTNER responsibility only)
• Catalog API
  • GET /partners/services — List all available services (paginated)
  • GET /partners/services/:serviceId — Get service details
  • GET /partners/timeslots/available — Query real-time available timeslots by address, service, and date
  • GET /partners/pricing/tiers — Retrieve active pricing tiers
  • POST /partners/pricing/calculate-price — Calculate price with coupon preview
• Webhooks API
  • POST /partners/webhooks/subscriptions — Create webhook subscription
  • GET /partners/webhooks/subscriptions — List subscriptions
  • PATCH /partners/webhooks/subscriptions/:id — Update subscription URL, events, or status
  • DELETE /partners/webhooks/subscriptions/:id — Remove subscription
  • POST /partners/webhooks/subscriptions/:id/rotate-secret — Rotate signing secret
  • GET /partners/webhooks/deliveries — List delivery history with filtering
  • POST /partners/webhooks/deliveries/:id/retry — Manually retry failed deliveries
• Webhook Events
  • booking.created
  • booking.updated
  • booking.cancelled
  • booking.payment_failed
  • booking.payment_confirmed
  • booking.appointment_status_changed
• Infrastructure
  • Per-partner sliding-window rate limiting (60-second window)
  • HMAC-SHA256 webhook signature verification
  • Automatic webhook retry: 3 retries at 1min, 5min, 15min intervals
  • Domain allowlist validation for webhook URLs and partner requests
  • X-Request-Id response header for request tracing
  • Partner booking external reference uniqueness enforcement

---

​

Versioning Policy

Partners will be notified at least 90 days in advance of any breaking change.

---

​

How to Stay Updated

• Watch for release announcements from your CleanLife integration contact.
• Monitor the X-API-Version response header (planned for future releases) to detect version changes.
• Subscribe to the CleanLife Partner Developer newsletter via your integration contact.