Payables: Managing the Invoice Lifecycle in Cleo Pay

A payable represents an invoice or bill in Cleo Pay. You create a payable to record what you owe a vendor, route it through an approval workflow, and then initiate one or more payments against it. Cleo Pay tracks two independent dimensions for every payable: the document lifecycle (is the invoice approved?) and the payment status (have funds been sent?). Understanding both dimensions is key to building reliable AP automation.

Document lifecycle status

The document status reflects where the payable sits in your approval workflow.

Status	Meaning
`draft`	The payable has been created but not yet submitted for approval. It cannot be paid in this state.
`pending_approval`	The payable has been submitted and is awaiting a reviewer’s decision.
`approved`	The payable has been approved and is eligible for payment.
`declined`	A reviewer has rejected the payable. It cannot be paid.
`blocked`	The payable has been administratively blocked. It cannot be paid.
`void`	The payable has been voided and is no longer active.

The typical happy path is: draft → pending_approval → approved.

Payment status

The payment status tracks the financial progress of the payable, independently of its document status. A payable must be approved before a payment can be initiated against it.

Payment Status	Meaning
`none`	No payment has been initiated yet.
`scheduled`	A payment has been scheduled but not yet sent.
`processing`	Funds are in transit via ACH.
`settled`	All funds have been received by the payee. The payable is fully paid.
`failed`	The payment attempt failed (e.g. insufficient funds or bank rejection).
`clawback`	Previously settled funds have been reversed or recalled.

These two status fields are orthogonal — a payable can be approved with payment status none (approved but not yet paid), or approved with payment status processing (approved and payment in flight). Always check both fields when building status-driven logic.

IDs: `id` vs `publicId`

Every payable has two identifiers:

id — an opaque internal identifier used in API requests (e.g. when creating a payment against a payable via payableId).
publicId — a stable, human-readable reference number shown in the dashboard and suitable for displaying in UIs, statements, or email subject lines (e.g. INV-00042). Also exposed as customNumber when you supply your own invoice number.

Use id in all API calls. Use publicId or customNumber in customer-facing surfaces.

Amount fields

All amounts are integers in cents.

Field	Description
`totalAmountCents`	The full invoice amount.
`amountPaidCents`	The cumulative amount paid so far across all payments.
`remainingAmountCents`	`totalAmountCents` minus `amountPaidCents`. This is how much is still owed.

When sending a payment against a payable without specifying amountCents, Cleo Pay defaults to the remainingAmountCents value, paying the invoice in full.

Date fields

Field	Format	Description
`issueDate`	`YYYY-MM-DD`	The date the invoice was issued. Nullable.
`dueDate`	`YYYY-MM-DD`	The date payment is due. Nullable.

Contact association

Each payable is associated with a contact representing the vendor. The contact object on a payable includes the contact’s id and displayName, allowing you to look up the full contact record at /v1/contacts/{id} if needed.

Line items

Payables support an array of items representing individual line items on the invoice.

Field	Type	Description
`name`	string	Short label for the line item (e.g. `"Consulting Services"`).
`description`	string	Optional longer description.
`quantity`	number	Number of units.
`unitAmountCents`	integer	Price per unit in cents.
`totalCents`	integer	`quantity × unitAmountCents`, in cents.

Example payable object

{
  "id": "pbl_01hrx3t7k2abcdef",
  "publicId": "INV-00042",
  "customNumber": "ACME-2025-042",
  "status": "approved",
  "paymentStatus": "processing",
  "totalAmountCents": 325000,
  "amountPaidCents": 150000,
  "remainingAmountCents": 175000,
  "issueDate": "2025-03-01",
  "dueDate": "2025-03-31",
  "description": "March consulting retainer",
  "contact": {
    "id": "con_01hq9r2m7tuvwxyz",
    "displayName": "Globex Supplies LLC"
  },
  "items": [
    {
      "name": "Consulting Services",
      "description": "Strategy consulting — 20 hours",
      "quantity": 20,
      "unitAmountCents": 15000,
      "totalCents": 300000
    },
    {
      "name": "Expense Reimbursement",
      "description": "Travel expenses",
      "quantity": 1,
      "unitAmountCents": 25000,
      "totalCents": 25000
    }
  ]
}

Next steps

Payments — initiate and track payments against a payable.
Contacts — understand the contact associated with each payable.

Get Started

Core Concepts

How-To Guides

Reference

Payables: Managing the Invoice Lifecycle in Cleo Pay

Document lifecycle status

Payment status

IDs: `id` vs `publicId`

Amount fields

Date fields

Contact association

Line items

Example payable object

Next steps

​Document lifecycle status

​Payment status

​IDs: id vs publicId

​Amount fields

​Date fields

​Contact association

​Line items

​Example payable object

​Next steps

Document lifecycle status

Payment status

IDs: `id` vs `publicId`

Amount fields

Date fields

Contact association

Line items

Example payable object

Next steps