Create your customers once through the API and then send your outstanding items every day, one call per item. The portal works out whether a collection order is new, changed or paid. Preferably also pass on payments separately, so the portal does not have to guess when an item was paid.
Why synchronise
When you synchronise, your system does not have to keep track of what has changed. You send the current state and the portal compares it with what it already knows. That keeps the integration simple on your side, even with little IT capacity. How the comparison works is explained in Collection Sync explained.
How to do it
- Create the customer with
POST /v3/debtors: name, contact details, address and any blocked channels. Do this once, for example as soon as the customer is created in your own system. - Update the customer with
PATCH /v3/debtors/{debtor_number}when something changes. You only send what is different. Changes are also passed on to that customer's running collection orders. - Send your outstanding items with
POST /v3/collection_orders/sync: per item the customer number, the payment reference and the invoices that are currently outstanding. You do not send customer details here; the portal takes them from step 1. - Read the response. It shows what the portal did (
created,updated,closed,unchanged) and which events were recorded. See Collection Sync: events and event codes. - Repeat step 3 for every item, for example every day at a fixed time.
How do you close a collection order?
When you synchronise per item, there is no moment at which the portal knows your list is complete. An item you no longer send keeps running. Choose one of these options:
| Option | When |
|---|---|
| Pass on the payment separately with the payment endpoint | Recommended. Your system knows when something was paid and passes it on straight away. See Passing on payments through the API. |
| Send amount 0 with the synchronisation | You keep sending a paid item for a while with outstanding amount 0, for example for a week. The collection order becomes Paid. |
| Deliver the complete list (planned) | For systems that can no longer send paid items. After your last synchronisation you send one list with all items that are still outstanding. Anything missing becomes Paid or Ended without payment. An empty list is rejected, so a failed export does not close everything. |
Advice: combine synchronising with the payment endpoint. A message that something was paid is more reliable than assuming an item was paid because it is missing.
Good to know
- If the customer does not exist yet, the synchronisation is rejected. Create the customer first.
- You cannot create a customer with
PATCH; usePOSTfor that. If the customer already exists,POSTreturns an error and you usePATCH. - The first flow step of a new collection order is scheduled one hour after the synchronisation. A new state within that hour is processed first.
- Each synchronisation costs 1 point. See Getting started with the API.