GET /v1/payables — List All Payables

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 object; retrieve a single payable with GET /v1/payables/ 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

number

default:"1"

The page number to return. Must be 1 or greater.

number

default:"25"

Number of payables to return per page. Minimum 1, maximum 100.

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

string

Free-text search string. Matched against invoice numbers, descriptions, and contact display names.

Example Request

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.

array

Array of Payable objects matching the query.

Show Payable object fields

string

Internal opaque identifier for the payable. Use this id when calling other endpoints that reference a specific payable.

string

Stable public identifier shown in the Cleo Pay dashboard. Safe to display in your own UI.

string

Current lifecycle status of the payable. One of: draft, pending_approval, approved, declined, blocked, void.

string

Current payment processing status. One of: none, scheduled, processing, settled, failed, clawback.

number

Total invoice amount in cents (e.g. 10000 = $100.00).

number

Amount already paid against this payable, in cents.

number

Outstanding balance remaining, in cents. Equals totalAmountCents - amountPaidCents.

string | null

Payment due date in YYYY-MM-DD format, or null if not set.

string | null

Invoice issue date in YYYY-MM-DD format, or null if not set.

string | null

Your own invoice or reference number, or null if not provided.

string | null

Free-text memo or description, or null if not provided.

object

The counterparty associated with this payable.

Show contact fields

string | null

Internal identifier of the contact record, or null if not resolved.

string | null

Human-readable name for the contact, or null if not available.

number

Total number of payables matching the current query, across all pages. Use this value to calculate page counts and drive pagination controls.

Example Response

{
  "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
}

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.

Payables

Bank Accounts

Contacts

Payments

GET /v1/payables — List All Payables

Request

Query Parameters

Example Request

Response

Example Response

​Request

​Query Parameters

​Example Request

​Response

​Example Response

Request

Query Parameters

Example Request

Response

Example Response