> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thecleanlife.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Release history and versioning policy.

All notable changes to the Partner API are documented in this file.

The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

***

## \[Unreleased]

### Added

* **Contacts API**
  * `POST /partners/contacts` — Register a customer contact; returns `id` (`contactId`) and optional `addressId` for booking
  * Optional address fields on contact creation: `latitude`, `longitude`, `cityName`, `districtName`, `streetName`
  * New permission: `partner_contacts_read`
* **Partner-specific pricing** — Each service in `GET /partners/services` may return a price configured exclusively for your partner account. `0` means deferred payment (no upfront charge). When set, that price is applied automatically to bookings created through your integration.
* **Cancellation reasons** — `GET /partners/bookings/cancellation-reasons` lists valid reasons; `reasonId` is required when calling `PATCH /partners/bookings/:bookingId/cancel`

### Changed

* **Create Contact** — Response now includes `addressId` when an address is created from the request
* **Create Contact** — `utmSource` is no longer accepted in the request body; it is assigned from your partner account name
* **Service Catalog** — `GET /partners/services` returns **categories** with nested `services` (paginated by category); each service includes `id`, `name`, and `price` only. The `price` field reflects your partner-specific rate when configured.
* **Timeslots** — `GET /partners/timeslots/available` returns `{ date, slots }` with `startAt`/`endAt` only (capacity fields are not exposed)
* **Create Booking** — `serviceId` is now **required**; `categoryId` is resolved automatically from the service and must not be sent
* **Create Booking** — `contactId` and `addressId` are required; obtain both from `POST /partners/contacts`
* **Create Booking** — Removed partner-facing fields: `packageId`, `customServices`, `hours`, `numberOfTeams`, `workType`, `userId`, `couponIds`, `codes`, `promoCode`, `contractCode`, `discountCode`, `tapId`, `paymentRedirectUrl`, `paymentId`
* **Create Booking** — Booking amount is determined by the partner-specific price configured for the selected service (when set), not the platform default price
* **Cancel Booking** — `reasonId` is now **required**; obtain valid values from `GET /partners/bookings/cancellation-reasons`

### Removed

* **Update Booking** — `PATCH /partners/bookings/:bookingId` removed from partner documentation
* **Get Service** — `GET /partners/services/:serviceId` removed from partner documentation

### 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/: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

* **Infrastructure**
  * Per-partner sliding-window rate limiting (60-second window)
  * Domain allowlist validation for partner requests
  * `X-Request-Id` response header for request tracing
  * Partner booking external reference uniqueness enforcement

***

## Versioning Policy

| Change Type                   | Version Bump | Notes                                  |
| ----------------------------- | ------------ | -------------------------------------- |
| New optional request fields   | No bump      | Backwards compatible                   |
| New response fields           | No bump      | Clients must tolerate unknown fields   |
| New optional query parameters | No bump      | Backwards compatible                   |
| Changed field types or names  | Major bump   | Breaking change — new URI version      |
| Removed endpoints or fields   | Major bump   | Breaking change — advance notice given |
| New required request fields   | Major bump   | Breaking change                        |
| Authentication scheme change  | Major bump   | Breaking change                        |

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.