custom-fields:read and custom-fields:write to sync, payables:read to read bills, and payables:write to create or submit bills with an event.
1
Create the field in the Cleo web app
An admin adds an Invoice-level question of type Dropdown, named “Event”, under Settings > Invoices > Custom Questions. Leave it optional for now. The API cannot create fields.The web app saves a dropdown only with at least one option. That first option has no
externalId, so a sync never changes it. If it is not one of your events, archive it in the web app after your first sync.2
Find the field id
Call
GET /v1/payable-custom-fields and find the field with "label": "Event", "scope": "ROOT" and "type": "DROPDOWN". Store its id. It does not change.3
Push your events
Send your events to
PUT /v1/payable-custom-fields/{fieldId}/options, with your event id as externalId and the event name as label.4
Send the event on bills you create
When your integration creates or submits a bill, send the event’s
externalId as the field’s answer in customFields.5
Mark the field required
Call
GET /v1/payable-custom-fields and check that the field lists your events. Then an admin marks it required, so the Cleo web app asks for an event when a vendor sends a bill through Cleo or someone at the business enters one. Before your events are synced, a required field makes vendors pick an option that is not one of your events, or refuses their bills when it has no options.A required field applies to the API too. Once it is required, a bill you create with submit: true, and every bill you submit, must name an event. That is why your integration sends the event first.6
Read and group bills
Read each bill’s answer by the field id, and map its
externalId back to your event. Or list one event’s bills with the customFieldId filter.Push your events
- A new event gets a new option.
- A renamed event keeps its option. Send the same
externalIdwith the newlabel. Bills that already chose it show the new name. - A finished or cancelled event is archived. Send it with
"archived": true. Vendors can no longer pick it, and its bills keep it. - A restored event is sent with
"archived": false. - An unchanged event is not written again, so resending the whole list is cheap and safe.
externalId values differ.
Send the event on a bill
Answer the Event field by itsfieldId, with your event id as value. Cleo matches it against each option’s id, then externalId, then value.
customFields to POST /v1/payables/{payableId}/submit. Your answer replaces any event already on the draft.
An event id the field does not have, or an archived event, fails with 422 validation_error. Sync your events first.
Read each bill’s event
Every bill carries its answers incustomFields. Find the answer whose fieldId is the Event field:
value.externalId to your event. Do not match on label: it changes when an event is renamed, and two events can share one. An option someone added in the Cleo web app has externalId: null. Match it by optionId instead.
A bill with no answer has no entry for the field, or an entry whose value is null. A required field still leaves gaps: bills created before it was required, and drafts, can have no event.
List one event’s bills
Pass the field id and your event id toGET /v1/payables:
customFieldValue also takes the option’s id or value. Archived events still match. Walk the pages until you have totalCount bills. See Pagination.
To total an event’s cost, add up totalAmountCents, or amountPaidCents for what has been paid. For per-line detail, read each bill with GET /v1/payables/{payableId}: its line items carry their own category and line-level customFields.
Bills from before the dropdown
If the business used a free-text question for events before, its old bills keep those text answers under the old field’sfieldId, as plain strings. Cleo does not convert them to options, and the filter does not match them. Map them to your events on your side, for example by reading each bill once and matching the text.
The old field stays on those bills even after it is turned off or deleted, with the label it had then. See Old and deleted answers.