Connections

Manage the payer-payee relationships between businesses on Cleo Pay.

A connection represents an established relationship between two businesses on Cleo Pay — a payer and a payee. Connections are required before creating payables or sending payments between businesses.

Connection statuses

Status	Description
active	The connection is established and both businesses can transact.
pending	An invitation has been sent but not yet accepted.
archived	The connection has been archived and is no longer active for transactions.

Connection fields

Field	Type	Description
id	string	Unique connection ID.
status	string	Current connection status.
alias	string	Your custom label for this connection.
tags	array	Tags for organization and filtering.
settings	object	Connection-specific settings (e.g., net terms).
businessName	string	Name of the connected business.
connectedBusinessName	string	Name of the other side of the connection.

---

List connections

GET /api/connections

Returns all active and archived connections for your businesses.

curl --request GET \
  --url https://api.cleo-pay.com/api/connections \
  --header "Authorization: Bearer <token>"

---

Get a connection

GET /api/connections/{connectionId}

Returns the full details of a single connection.

Path parameters

connectionId · string · required

The unique ID of the connection.

curl --request GET \
  --url https://api.cleo-pay.com/api/connections/conn_def456 \
  --header "Authorization: Bearer <token>"

---

Update alias

PATCH /api/connections/{connectionId}/alias

Sets a custom display name for the connection. The alias only affects how the connection appears to your business.

Path parameters

connectionId · string · required

The unique ID of the connection.

Request body

alias · string · required

The new alias for the connection.

curl --request PATCH \
  --url https://api.cleo-pay.com/api/connections/conn_def456/alias \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{ "alias": "Acme Vendor" }'

---

Update tags

PATCH /api/connections/{connectionId}/tags

Replaces the current tag set for a connection. Tags are used to organize and filter connections.

Path parameters

connectionId · string · required

The unique ID of the connection.

Request body

tagIds · array · required

Array of tag IDs to assign to the connection.

curl --request PATCH \
  --url https://api.cleo-pay.com/api/connections/conn_def456/tags \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{ "tagIds": ["tag_001", "tag_002"] }'

---

Update settings

PATCH /api/connections/{connectionId}/settings

Updates connection-level settings such as net payment terms and auto-approval rules.

Path parameters

connectionId · string · required

The unique ID of the connection.

Request body

netTerms · number

Default net payment terms in days (e.g., 30 for Net 30).

curl --request PATCH \
  --url https://api.cleo-pay.com/api/connections/conn_def456/settings \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{ "netTerms": 30 }'

---

Archive a connection

PATCH /api/connections/{connectionId}/archive

Archives a connection. Archived connections no longer appear in the active connections list and cannot be used to create new payables.

Path parameters

connectionId · string · required

The unique ID of the connection to archive.

curl --request PATCH \
  --url https://api.cleo-pay.com/api/connections/conn_def456/archive \
  --header "Authorization: Bearer <token>"

---

List invoices for a connection

GET /api/connections/{connectionId}/invoices

Returns all payables associated with a specific connection.

Path parameters

connectionId · string · required

The unique ID of the connection.

curl --request GET \
  --url https://api.cleo-pay.com/api/connections/conn_def456/invoices \
  --header "Authorization: Bearer <token>"

---

Export connections as CSV

GET /api/connections/export-csv

Exports all connections as a CSV file for reporting or record-keeping.

curl --request GET \
  --url https://api.cleo-pay.com/api/connections/export-csv \
  --header "Authorization: Bearer <token>"