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