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

page

number

default:"1"

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

pageSize

number

default:"25"

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

status

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.

items

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.

publicId

string

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

status

string

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

paymentStatus

string

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

totalAmountCents

number

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

amountPaidCents

number

Amount already paid against this payable, in cents.

remainingAmountCents

number

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

dueDate

string | null

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

issueDate

string | null

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

customNumber

string | null

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

description

string | null

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

contact

object

The counterparty associated with this payable.

Show contact fields

string | null

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

displayName

string | null

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

totalCount

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