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

# GET /v1/payables — List All Payables

> GET /v1/payables returns a paginated list of payables. Filter by status, search by text, and paginate with page and pageSize parameters.

The List Payables endpoint returns a paginated collection of all payables in your account. You can narrow results by lifecycle status, run a free-text search across invoice numbers, descriptions, and contact names, and control page size to suit your UI or data-pipeline needs. Each item in the response is a summary-level [Payable](#response) object; retrieve a single payable with [GET /v1/payables/{payableId}](/api-reference/payables/get) to access full line-item detail.

## Request

**`GET https://api.cleo-pay.com/v1/payables`**

Include your bearer token in every request:

```
Authorization: Bearer <token>
```

### Query Parameters

<ParamField query="page" type="number" default="1">
  The page number to return. Must be `1` or greater.
</ParamField>

<ParamField query="pageSize" type="number" default="25">
  Number of payables to return per page. Minimum `1`, maximum `100`.
</ParamField>

<ParamField query="status" type="string">
  Filter results to payables matching a specific lifecycle status. Accepted values:

  | Value              | Description                                |
  | ------------------ | ------------------------------------------ |
  | `draft`            | Created but not yet submitted for approval |
  | `pending_approval` | Submitted and awaiting review              |
  | `approved`         | Approved and eligible for payment          |
  | `declined`         | Rejected during the approval process       |
  | `blocked`          | Temporarily blocked from processing        |
  | `void`             | Cancelled and no longer actionable         |
</ParamField>

<ParamField query="search" type="string">
  Free-text search string. Matched against invoice numbers, descriptions, and contact display names.
</ParamField>

### Example Request

```bash theme={null}
curl --request GET \
  --url "https://api.cleo-pay.com/v1/payables?page=1&pageSize=25&status=approved" \
  --header "Authorization: Bearer <token>"
```

## Response

A successful request returns HTTP `200` with a JSON body containing a paginated list of payable objects.

<ResponseField name="items" type="array">
  Array of Payable objects matching the query.

  <Expandable title="Payable object fields">
    <ResponseField name="id" type="string">
      Internal opaque identifier for the payable. Use this id when calling other endpoints that reference a specific payable.
    </ResponseField>

    <ResponseField name="publicId" type="string">
      Stable public identifier shown in the Cleo Pay dashboard. Safe to display in your own UI.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current lifecycle status of the payable. One of: `draft`, `pending_approval`, `approved`, `declined`, `blocked`, `void`.
    </ResponseField>

    <ResponseField name="paymentStatus" type="string">
      Current payment processing status. One of: `none`, `scheduled`, `processing`, `settled`, `failed`, `clawback`.
    </ResponseField>

    <ResponseField name="totalAmountCents" type="number">
      Total invoice amount in cents (e.g. `10000` = \$100.00).
    </ResponseField>

    <ResponseField name="amountPaidCents" type="number">
      Amount already paid against this payable, in cents.
    </ResponseField>

    <ResponseField name="remainingAmountCents" type="number">
      Outstanding balance remaining, in cents. Equals `totalAmountCents - amountPaidCents`.
    </ResponseField>

    <ResponseField name="dueDate" type="string | null">
      Payment due date in `YYYY-MM-DD` format, or `null` if not set.
    </ResponseField>

    <ResponseField name="issueDate" type="string | null">
      Invoice issue date in `YYYY-MM-DD` format, or `null` if not set.
    </ResponseField>

    <ResponseField name="customNumber" type="string | null">
      Your own invoice or reference number, or `null` if not provided.
    </ResponseField>

    <ResponseField name="description" type="string | null">
      Free-text memo or description, or `null` if not provided.
    </ResponseField>

    <ResponseField name="contact" type="object">
      The counterparty associated with this payable.

      <Expandable title="contact fields">
        <ResponseField name="id" type="string | null">
          Internal identifier of the contact record, or `null` if not resolved.
        </ResponseField>

        <ResponseField name="displayName" type="string | null">
          Human-readable name for the contact, or `null` if not available.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalCount" type="number">
  Total number of payables matching the current query, across all pages. Use this value to calculate page counts and drive pagination controls.
</ResponseField>

### Example Response

```json theme={null}
{
  "items": [
    {
      "id": "pay_01hx9k2mq3fvb8n7cptd6ewrja",
      "publicId": "PAY-2024-00042",
      "status": "approved",
      "paymentStatus": "scheduled",
      "totalAmountCents": 250000,
      "amountPaidCents": 0,
      "remainingAmountCents": 250000,
      "dueDate": "2024-08-15",
      "issueDate": "2024-07-15",
      "customNumber": "INV-1042",
      "description": "Q3 software licensing fees",
      "contact": {
        "id": "con_01hx8a1bc2def3gh4ijk5lm6no",
        "displayName": "Acme Corporation"
      }
    },
    {
      "id": "pay_01hx9k2mq3fvb8n7cptd6ewrjb",
      "publicId": "PAY-2024-00041",
      "status": "approved",
      "paymentStatus": "settled",
      "totalAmountCents": 75000,
      "amountPaidCents": 75000,
      "remainingAmountCents": 0,
      "dueDate": "2024-07-01",
      "issueDate": "2024-06-01",
      "customNumber": "INV-1041",
      "description": "Implementation services — Phase 1",
      "contact": {
        "id": "con_01hx8a1bc2def3gh4ijk5lm6np",
        "displayName": "Globex Partners LLC"
      }
    }
  ],
  "totalCount": 84
}
```

<Tip>
  Use `totalCount` together with your chosen `pageSize` to calculate the total number of pages: `Math.ceil(totalCount / pageSize)`. For example, `totalCount: 84` with `pageSize: 25` yields 4 pages. Increment `page` from `1` to that ceiling to iterate through all results.
</Tip>