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

# Clients Abilities

> 11 abilities for managing MainWP client records and their associated sites.

MainWP registers 11 client management abilities into the WordPress Abilities API framework. These enable programmatic management of client records, site associations, and client-level operations.

## What You'll Learn

* Listing, filtering, and retrieving client information
* Creating, updating, and deleting clients
* Managing client site associations
* Suspending and unsuspending clients
* Retrieving client cost data

***

## mainwp/list-clients-v1

List MainWP clients with pagination and filtering.

**Method:** GET (readonly)

```bash theme={null}
curl -u 'admin:xxxx' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/list-clients-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `page` | integer | No | 1 | Page number |
| `per_page` | integer | No | 20 | Items per page (max 100) |
| `status` | string | No | "any" | Filter: `any`, `active`, `suspended` |
| `search` | string | No | "" | Search term |
| `include` | array | No | \[] | Client IDs to include |
| `exclude` | array | No | \[] | Client IDs to exclude |

**Response:**

```json theme={null}
{
  "items": [
    {
      "id": 1,
      "name": "Acme Corp",
      "email": "contact@acme.com",
      "phone": "+1-555-0100",
      "status": "active",
      "sites_count": 5,
      "created_at": "2023-01-15T10:00:00Z"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 25
}
```

***

## mainwp/count-clients-v1

Get total count of clients.

**Method:** GET (readonly)

```bash theme={null}
curl -u 'admin:xxxx' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/count-clients-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `status` | string | No | "any" | Filter: `any`, `active`, `suspended` |

**Response:**

```json theme={null}
{
  "total": 25
}
```

***

## mainwp/get-client-v1

Get detailed information about a single client.

**Method:** GET (readonly)

```bash theme={null}
curl -G -u 'admin:xxxx' \
  --data-urlencode 'input_json={"client_id_or_email":1}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-client-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `client_id_or_email` | integer\|string | Yes | — | Client ID or email address |

**Response:**

```json theme={null}
{
  "id": 1,
  "name": "Acme Corp",
  "email": "contact@acme.com",
  "phone": "+1-555-0100",
  "address_1": "123 Main Street",
  "address_2": "Suite 100",
  "city": "New York",
  "state": "NY",
  "zip": "10001",
  "country": "United States",
  "note": "Premium client",
  "status": "active",
  "sites_count": 5,
  "created_at": "2023-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}
```

***

## mainwp/add-client-v1

Create a new client.

**Method:** POST

```bash theme={null}
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"name":"New Client","client_email":"client@example.com","client_phone":"+1-555-0100"}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/add-client-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `name` | string | Yes | — | Client name |
| `client_email` | string | No | — | Email address |
| `client_phone` | string | No | — | Phone number |
| `address_1` | string | No | — | Address line 1 |
| `address_2` | string | No | — | Address line 2 |
| `city` | string | No | — | City |
| `state` | string | No | — | State/Province |
| `zip` | string | No | — | ZIP/Postal code |
| `country` | string | No | — | Country |
| `note` | string | No | — | Notes |
| `selected_sites` | array | No | — | Site IDs to associate |

**Response:**

Returns the created client object (same format as `get-client-v1`).

***

## mainwp/update-client-v1

Update an existing client.

**Method:** POST

```bash theme={null}
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1,"name":"Updated Name","note":"New notes"}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/update-client-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `client_id_or_email` | integer\|string | Yes | — | Client ID or email |
| `name` | string | No | — | Client name |
| `client_email` | string | No | — | Email address |
| `client_phone` | string | No | — | Phone number |
| `address_1` | string | No | — | Address line 1 |
| `address_2` | string | No | — | Address line 2 |
| `city` | string | No | — | City |
| `state` | string | No | — | State/Province |
| `zip` | string | No | — | ZIP/Postal code |
| `country` | string | No | — | Country |
| `note` | string | No | — | Notes |
| `selected_sites` | array | No | — | Site IDs to associate (replaces existing) |

**Response:**

Returns the updated client object.

***

## mainwp/delete-client-v1

Delete a client. This is a destructive operation that requires confirmation.

**Method:** POST

```bash theme={null}
# Dry run to preview
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1,"dry_run":true}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/delete-client-v1/run'

# Actual deletion
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1,"confirm":true}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/delete-client-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `client_id_or_email` | integer\|string | Yes | — | Client ID or email |
| `confirm` | boolean | Yes | — | Must be `true` to confirm deletion |
| `dry_run` | boolean | No | false | Preview without deleting |

**Response:**

```json theme={null}
{
  "deleted": true,
  "client_id": 1,
  "client_name": "Acme Corp"
}
```

***

## mainwp/get-client-sites-v1

Get sites associated with a client.

**Method:** GET (readonly)

```bash theme={null}
curl -G -u 'admin:xxxx' \
  --data-urlencode 'input_json={"client_id_or_email":1}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-client-sites-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `client_id_or_email` | integer\|string | Yes | — | Client ID or email |
| `page` | integer | No | 1 | Page number |
| `per_page` | integer | No | 20 | Items per page |

**Response:**

```json theme={null}
{
  "client_id": 1,
  "client_name": "Acme Corp",
  "sites": [
    {
      "id": 1,
      "url": "https://site1.example.com",
      "name": "Site 1",
      "status": "connected"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 5
}
```

***

## mainwp/count-client-sites-v1

Count sites associated with a client.

**Method:** GET (readonly)

```bash theme={null}
curl -G -u 'admin:xxxx' \
  --data-urlencode 'input_json={"client_id_or_email":1}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/count-client-sites-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `client_id_or_email` | integer\|string | Yes | — | Client ID or email |

**Response:**

```json theme={null}
{
  "client_id": 1,
  "client_name": "Acme Corp",
  "sites_count": 5
}
```

***

## mainwp/get-client-costs-v1

Get cost tracker entries for a client. Requires the Cost Tracker module to be active.

**Method:** GET (readonly)

```bash theme={null}
curl -G -u 'admin:xxxx' \
  --data-urlencode 'input_json={"client_id_or_email":1}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-client-costs-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `client_id_or_email` | integer\|string | Yes | — | Client ID or email |

**Response:**

```json theme={null}
{
  "items": [
    {
      "id": 12,
      "name": "Shared Hosting",
      "type": "subscription",
      "price": 89,
      "renewal_type": "monthly",
      "payment_method": "credit_debit",
      "product_type": "hosting",
      "last_renewal": "2026-06-29T00:00:00+00:00",
      "next_renewal": "2026-11-29T00:00:00+00:00",
      "purchase_date": "2026-06-29T00:00:00+00:00",
      "license_type": "multi_site",
      "sites_count": 10,
      "client_share": 17.8
    }
  ],
  "total": 1
}
```

**Response fields for each cost:**

| Field | Description |
| - | - |
| `id`, `name` | Cost ID and name |
| `type` | `subscription` (recurring) or `lifetime` (one-time) |
| `price` | Price for one renewal period. For `single_site`, this price applies to each covered site. For `multi_site`, this is the total price split across covered sites |
| `renewal_type` | How often it renews: `weekly`, `monthly`, `quarterly`, `yearly` or `disabled` |
| `purchase_date` | Date the cost was bought |
| `last_renewal` | Same value as `purchase_date`. Still returned for existing integrations; it does not move forward as renewals pass |
| `next_renewal` | Next renewal date, the same date the Cost Tracker shows. `null` for lifetime costs and costs that aren't active |
| `license_type` | `single_site` (full price for each site) or `multi_site` (price split across the cost's sites) |
| `sites_count` | Number of sites the cost covers, including sites added through groups or clients |
| `client_share` | This client's part of the price for each renewal period: the per-site amount times the number of the client's sites the cost covers. In the example, 2 of the 10 sites belong to the client. `0` when the cost isn't active |

> [!NOTE]
>
> This ability requires the Cost Tracker module. If inactive, returns `mainwp_module_not_available` error.

***

## mainwp/suspend-client-v1

Suspend a client. This also suspends all associated sites.

**Method:** POST

```bash theme={null}
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/suspend-client-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `client_id_or_email` | integer\|string | Yes | — | Client ID or email |

**Response:**

```json theme={null}
{
  "suspended": true,
  "client_id": 1,
  "client_name": "Acme Corp",
  "sites_suspended": 5
}
```

***

## mainwp/unsuspend-client-v1

Unsuspend a previously suspended client. This also unsuspends all associated sites.

**Method:** POST

```bash theme={null}
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/unsuspend-client-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `client_id_or_email` | integer\|string | Yes | — | Client ID or email |

**Response:**

```json theme={null}
{
  "unsuspended": true,
  "client_id": 1,
  "client_name": "Acme Corp",
  "sites_unsuspended": 5
}
```

***

## Related Resources

* [Abilities API Overview](https://docs.mainwp.com/api-reference/abilities-api/overview.md) - API basics and authentication
* [Sites Abilities](https://docs.mainwp.com/api-reference/abilities-api/sites.md) - Site management abilities
* [REST API Clients](https://docs.mainwp.com/api-reference/rest-api/clients.md) - REST API alternative for clients
* [Manage Clients](https://docs.mainwp.com/clients/manage-clients.md) - Client management in Dashboard


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.