- Webhooks tell you that something changed. On each
payable.*orpayment.*event, re-read that resource. - A scheduled poll catches everything else.
GET /v1/payablesandGET /v1/paymentstakeupdatedSince, so each poll reads only what changed.
payables:read, which reads both bills and payments, and webhooks:manage to register the endpoint. Webhooks are in early access. Ask your Cleo contact to turn them on for the business.
1
Load everything once
Walk
GET /v1/payables?updatedSince=2000-01-01T00:00:00Z&expand=items and GET /v1/payments?updatedSince=2000-01-01T00:00:00Z page by page. Store each record by id. Set each resource’s cursor to the largest updatedAt it returned.2
Register a webhook endpoint
Subscribe to the
payable.* and payment.* events you need. See Create a webhook endpoint.3
Re-read on each event
Fetch the resource the event names and upsert it. Do not move a cursor.
4
Poll on a schedule
Every few minutes, or as often as you need, read what changed since 5 minutes before each cursor and upsert it. Then move that cursor to the largest
updatedAt you read.Register the endpoint
payable.* events reach the payer as well as the business that created the bill. A bill a vendor sends to the business reaches your endpoint. See Who receives each event.
Re-read on each event
An event names a resource indata.object and data.id. It carries no state.
- Upsert what the
GETreturns byid. - Do not rebuild a resource’s state from the sequence of event types. Events can arrive late, twice or out of order.
- Do not assume
payable.createdis the first event you get for a bill. Re-read on any event. - Never move a poll cursor from a record you fetched because of a webhook. That record can carry a newer
updatedAtthan a change the poll has not reached yet. Starting the next poll from it would skip that change.
2xx first, then fetch. See Webhooks.
Poll on a schedule
Keep one cursor for bills and one for payments, stored apart from the records. Each poll:- Calls the list with
updatedSinceset a fixed safety window, such as 5 minutes, before the cursor. A change’supdatedAtis set before it commits, so a change can appear after a poll has passed its timestamp. The overlap catches it. - Reads every page. Results come oldest change first, by
updatedAtand thenid. - Upserts each record by
id.updatedSinceis inclusive and the window overlaps the last poll, so expect to see some records again. - Sets the cursor to the largest
updatedAtthe poll returned. Never set it to the current time: a change that has not committed yet would fall behind the cursor and never be read. Bulk changes send no webhook, so the poll is the only way to find them.
expand=items, one call returns up to 100 bills with their line items, so you do not need one call per bill.
What moves updatedAt
A bill’s updatedAt moves when anything the API returns about it changes: its fields, status, line items, custom field answers, categories, tags and attachments. A payment’s updatedAt moves when the payment changes.
Some changes send no payable.updated but still move updatedAt, so only the poll finds them: merging a category, disconnecting an accounting integration, and deleting a tag.
Some changes alter what the API returns for many bills without moving their updatedAt. Neither webhooks nor the poll report them:
- renaming or archiving a category;
- renaming a tag;
- relabelling a custom field or one of its options;
- renaming a contact.
GET /v1/payable-custom-fields or GET /v1/contacts, or re-read the affected bills.
A bill’s paymentStatus comes from its payments. Poll payments as well as bills to follow payment progress.