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

# Paginate, Sort, and Filter Shiipp Customers via API

> GET /api/ManageCustomers.php — retrieve a paginated, sortable list of customers with optional search, branch, and courier filtering. JWT token required.

The **ManageCustomers** endpoint returns a paginated, sortable list of customer records associated with your Shiipp courier account. An optional `search` parameter lets you filter results by user code or name, and you can sort by any of the supported fields.

## Endpoint

```
GET /api/ManageCustomers.php
```

**Authentication:** JWT Bearer token required.

```
Authorization: Bearer <your_token>
```

***

## Query Parameters

<ParamField query="page" type="integer" default="1">
  The page number to retrieve. Pagination starts at `1`.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of customer records to return per page. Maximum allowed value is `100`.
</ParamField>

<ParamField query="search" type="string">
  Optional search term. When provided, results are filtered to customers whose `user_code` or name contain the search string (wildcard partial match, case-insensitive).
</ParamField>

<ParamField query="branch" type="string">
  Filter results to customers assigned to a specific branch location (exact match).
</ParamField>

<ParamField query="courier_id" type="string">
  Filter results to a specific courier organization. **Admin and manager roles only.** Courier role users are automatically scoped to their own courier.
</ParamField>

<ParamField query="sort_by" type="string" default="first_name">
  Field to sort results by. Accepted values: `user_code`, `first_name`, `last_name`, `branch`, `courier_name`, `created_at`, `updated_at`.
</ParamField>

<ParamField query="sort_dir" type="string" default="ASC">
  Sort direction. Accepted values: `ASC`, `DESC`.
</ParamField>

***

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://app.shiipp.com/api/ManageCustomers.php?page=1&limit=20&search=Jane&sort_by=last_name&sort_dir=ASC" \
    -H "Authorization: Bearer <your_token>"
  ```
</CodeGroup>

***

## Response

```json theme={null}
{
  "status": "success",
  "data": [
    {
      "courier_customer_id": "cust-uuid",
      "user_code": "CUST001",
      "first_name": "Jane",
      "last_name": "Smith",
      "branch": "Kingston",
      "is_active": 1,
      "courier_name": "Express Couriers",
      "created_at": "2024-01-01 08:00:00",
      "updated_at": "2024-03-15 10:30:00"
    }
  ],
  "total": 312
}
```

### Response Fields

<ResponseField name="status" type="string">
  `"success"` when the request was processed without error.
</ResponseField>

<ResponseField name="data" type="array">
  Array of customer objects matching the search criteria.

  <Expandable title="Customer object fields">
    <ResponseField name="courier_customer_id" type="string">
      Unique UUID identifying this customer record.
    </ResponseField>

    <ResponseField name="user_code" type="string">
      The customer's unique user code within the courier account.
    </ResponseField>

    <ResponseField name="first_name" type="string">
      Customer's first name.
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Customer's last name.
    </ResponseField>

    <ResponseField name="branch" type="string">
      The branch or pickup location associated with this customer, if set.
    </ResponseField>

    <ResponseField name="is_active" type="integer">
      Whether the customer is active. `1` = active, `0` = inactive.
    </ResponseField>

    <ResponseField name="courier_name" type="string">
      The name of the courier organization this customer belongs to.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Timestamp when the customer record was created. Format: `YYYY-MM-DD HH:MM:SS`.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Timestamp when the customer record was last updated. Format: `YYYY-MM-DD HH:MM:SS`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of customers matching the search term across all pages.
</ResponseField>

***

## Get Branch List

Append `?action=branches` to retrieve the distinct list of branch names available for the authenticated courier. This is useful for populating filter dropdowns in your UI.

```
GET /api/ManageCustomers.php?action=branches
```

```json theme={null}
{
  "status": "success",
  "data": ["Kingston", "Montego Bay", "Ocho Rios", "Mandeville"]
}
```

***

## Pagination

To iterate through all customers, increment `page` until you have retrieved `total` records.

```bash theme={null}
GET /api/ManageCustomers.php?page=2&limit=20
```

<Tip>
  Use the `branch` filter together with `?action=branches` to build dynamic, pre-populated dropdowns in your UI — first fetch the branch list, then filter customers by the user's selected branch.
</Tip>

<Note>
  The `search` filter matches across `user_code` and customer names simultaneously. A single term like `"Jane"` will surface matches in any of those fields.
</Note>