> ## 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.

# Payables: Managing the Invoice Lifecycle in Cleo Pay

> Payables are invoices in Cleo Pay. Learn the document status lifecycle, payment progress tracking, line items, and how to use them in your AP workflow.

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. |

<Info>
  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.
</Info>

## 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. |

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

## 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

```json theme={null}
{
  "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](/concepts/payments) — initiate and track payments against a payable.
* [Contacts](/concepts/contacts) — understand the contact associated with each payable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.