> ## 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.

# List Services

> GET /partners/services — List service categories and their services at a customer address.

## Overview

Returns a paginated list of **service categories**, each containing the **services your partner account can offer at a specific customer address**. Results are the intersection of:

1. Services enabled for your partner account (when restrictions are configured), **and**
2. Services available in the service zone that covers the address coordinates.

Call `POST /partners/contacts` first to obtain an `addressId`, then pass it here to discover valid `serviceId` values for booking and timeslot queries.

***

## Endpoint

```
GET /partners/services
```

## Authentication

Requires a valid API Key with the `partner_services_read` permission.

***

## Query Parameters

| Parameter   | Type    | Required | Description                                                                                                      |
| ----------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `addressId` | UUID    | **Yes**  | Customer service address ID from `POST /partners/contacts` (`data.addressId`). Must have latitude and longitude. |
| `page`      | integer | No       | Page number (categories). Default: `1`.                                                                          |
| `limit`     | integer | No       | Categories per page. Default: `20`. Max: `100`.                                                                  |

***

## Example Request

```bash theme={null}
curl -X GET "https://apiv3.thecleanlife.dev/v1/partners/services?addressId=bbbbbbbb-0000-0000-0000-000000000002&page=1&limit=50" \
  -H "x-api-key: YOUR_API_KEY"
```

***

## Success Response

**HTTP Status:** `200 OK`

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "cccccccc-0000-0000-0000-000000000003",
      "code": "REGULAR_CLEANING",
      "nameEn": "Regular Cleaning",
      "nameAr": "تنظيف عادي",
      "descriptionEn": "Standard home cleaning service",
      "descriptionAr": "خدمة تنظيف منزلية",
      "isActive": true,
      "services": [
        {
          "id": "dddddddd-0000-0000-0000-000000000004",
          "name": "2 Hours Cleaning",
          "price": 150
        },
        {
          "id": "eeeeeeee-0000-0000-0000-000000000005",
          "name": "3 Hours Cleaning",
          "price": 200
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}
```

### Response fields

**Category object**

| Field           | Type           | Description                                                                            |
| --------------- | -------------- | -------------------------------------------------------------------------------------- |
| `id`            | UUID           | Category ID (for display/grouping only — do **not** send as `categoryId` when booking) |
| `code`          | string \| null | Category code                                                                          |
| `nameEn`        | string         | English name                                                                           |
| `nameAr`        | string         | Arabic name                                                                            |
| `descriptionEn` | string         | English description                                                                    |
| `descriptionAr` | string         | Arabic description                                                                     |
| `isActive`      | boolean        | Whether the category is active                                                         |
| `services`      | array          | Services in this category available at the address                                     |

**Service object (nested in `services`)**

| Field   | Type   | Description                                                                                                                                                                                                                                                                                                        |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`    | UUID   | Service ID — use as `serviceId` when creating a booking                                                                                                                                                                                                                                                            |
| `name`  | string | Service name                                                                                                                                                                                                                                                                                                       |
| `price` | number | Price in SAR for your partner account. When CleanLife configures a partner-specific price, that value is returned (`0` means deferred payment — no upfront charge). If no partner price is configured for a service, the platform default price applies. The same price is locked on the booking at creation time. |

Categories are ordered by internal sort order, then English name. Services within each category are ordered by name.

Pagination applies to **categories** (top-level `data` items), not individual services.

***

## Error Responses

| HTTP Status | Code                 | Description                                                   |
| ----------- | -------------------- | ------------------------------------------------------------- |
| `400`       | `VALIDATION_ERROR`   | Missing or invalid `addressId`, or address has no coordinates |
| `401`       | `UNAUTHORIZED`       | Missing or invalid API key                                    |
| `403`       | `FORBIDDEN`          | Missing `partner_services_read` permission                    |
| `404`       | `RESOURCE_NOT_FOUND` | Address not found                                             |

***

## Notes

* Always call this endpoint **after** `POST /partners/contacts` so you have an `addressId` with coordinates.
* Cache results per `addressId` with a short TTL (e.g., 15–60 minutes). Availability can change as zones are updated.
* Use `services[].id` as `serviceId` when creating bookings. You do **not** need to send `categoryId` — it is resolved automatically from the service.
* **`price` is partner-specific.** The value returned for each service reflects the price configured for your partner account. A value of `0` means **deferred payment** (no upfront charge). Display this price to your customers — it is the amount that will be charged when you create a booking for that service.
* An empty `data` array is a valid response — the address may be outside all service zones or no enabled service is available there.

***

## Related Endpoints

* `POST /partners/contacts` — Register the customer and obtain `addressId`
* `GET /partners/timeslots/available` — Get available timeslots for a service at the same address