POST /v1/payables — Create a New Payable

The Create Payable endpoint lets you programmatically generate a new payable (invoice) in Cleo Pay. You supply at minimum a contact and a total amount; optionally, you can attach structured line items, set issue and due dates, provide your own reference number, and add a free-text description. Newly created payables start in draft status and must proceed through your configured approval workflow before payment can be initiated.

Request

POST https://api.cleo-pay.com/v1/payables Include your bearer token and set the content type on every request:

Authorization: Bearer <token>
Content-Type: application/json

Request Body Parameters

contact

object

required

The counterparty for this payable. Cleo Pay will match against existing contacts by email, or create a new contact record if no match is found.

Show contact fields

name

string

required

Full display name of the contact (e.g. "Acme Corporation").

string

Email address of the contact. Used to match or create a contact record. Optional, but recommended for deduplication.

totalAmountCents

number

required

Total invoice amount expressed in cents. Must be 1 or greater (e.g. pass 10000 for $100.00). If you also supply items, ensure this value equals the sum of all items[].totalCents to avoid reconciliation discrepancies.

dueDate

string

Payment due date in YYYY-MM-DD format (e.g. "2024-08-15"). Optional. When omitted, the payable is created without a due date.

issueDate

string

Invoice issue date in YYYY-MM-DD format (e.g. "2024-07-15"). Optional. Defaults to the creation date when omitted.

customNumber

string

Your own invoice or purchase-order reference number (e.g. "INV-1042"). Optional. This value is stored as-is and surfaced in the dashboard alongside the system-generated publicId.

description

string

Free-text memo or description for this payable (e.g. "Q3 software licensing fees"). Optional.

items

array

Structured line items that make up the invoice. Optional. Each element represents one line on the invoice.

Show item fields

name

string

Short label for the line item (e.g. "Professional Services"). Optional.

description

string

Longer description of the line item. Optional.

quantity

number

required

Number of units for this line item. Must be a positive number.

unitAmountCents

number

required

Price per unit in cents. Must be a positive number (e.g. 5000 = $50.00 per unit).

Example Request

curl --request POST \
  --url "https://api.cleo-pay.com/v1/payables" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "contact": {
      "name": "Acme Corporation",
      "email": "ap@acme.example.com"
    },
    "totalAmountCents": 250000,
    "dueDate": "2024-08-15",
    "issueDate": "2024-07-15",
    "customNumber": "INV-1042",
    "description": "Q3 software licensing fees",
    "items": [
      {
        "name": "Enterprise License",
        "description": "Annual seat license — 10 users",
        "quantity": 10,
        "unitAmountCents": 20000
      },
      {
        "name": "Implementation Support",
        "description": "Onboarding and configuration services",
        "quantity": 5,
        "unitAmountCents": 10000
      }
    ]
  }'

Response

A successful request returns HTTP 201 Created with the full PayableDetail object, including all line items as stored.

string

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

publicId

string

Stable public identifier shown in the Cleo Pay dashboard.

status

string

Initial lifecycle status of the payable. Newly created payables always start as draft.

paymentStatus

string

Initial payment status. Always none for newly created payables.

totalAmountCents

number

Total invoice amount in cents, as provided in the request.

amountPaidCents

number

Amount paid so far, in cents. Always 0 for newly created payables.

remainingAmountCents

number

Outstanding balance in cents. Equal to totalAmountCents for newly created payables.

dueDate

string | null

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

issueDate

string | null

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

customNumber

string | null

Your custom reference number as stored, or null if not provided.

description

string | null

Memo or description as stored, or null if not provided.

contact

object

Resolved contact record associated with this payable.

Show contact fields

string | null

Internal identifier of the matched or created contact record.

displayName

string | null

Display name of the contact as stored.

items

array

Line items attached to this payable, as stored.

Show item fields

name

string | null

Line item label, or null if not provided.

description

string | null

Line item description, or null if not provided.

quantity

number

Number of units for this line item.

unitAmountCents

number

Price per unit in cents.

totalCents

number

Computed total for this line item in cents (quantity × unitAmountCents).

Example Response

{
  "id": "pay_01hx9k2mq3fvb8n7cptd6ewrja",
  "publicId": "PAY-2024-00042",
  "status": "draft",
  "paymentStatus": "none",
  "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"
  },
  "items": [
    {
      "name": "Enterprise License",
      "description": "Annual seat license — 10 users",
      "quantity": 10,
      "unitAmountCents": 20000,
      "totalCents": 200000
    },
    {
      "name": "Implementation Support",
      "description": "Onboarding and configuration services",
      "quantity": 5,
      "unitAmountCents": 10000,
      "totalCents": 50000
    }
  ]
}

Payables

Bank Accounts

Contacts

Payments

POST /v1/payables — Create a New Payable

Request

Request Body Parameters

Example Request

Response

Example Response

​Request

​Request Body Parameters

​Example Request

​Response

​Example Response

Request

Request Body Parameters

Example Request

Response

Example Response