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

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

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.

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.

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.

string

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

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.

string

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

array

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

Show item fields

string

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

string

Longer description of the line item. Optional.

number

required

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

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.

string

Stable public identifier shown in the Cleo Pay dashboard.

string

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

string

Initial payment status. Always none for newly created payables.

number

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

number

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

number

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

string | null

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

string | null

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

string | null

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

string | null

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

object

Resolved contact record associated with this payable.

Show contact fields

string | null

Internal identifier of the matched or created contact record.

string | null

Display name of the contact as stored.

array

Line items attached to this payable, as stored.

Show item fields

string | null

Line item label, or null if not provided.

string | null

Line item description, or null if not provided.

number

Number of units for this line item.

number

Price per unit in cents.

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