Creates a CollectionOrder resource.

This endpoint synchronises the outstanding amount of a single debtor and payment reference with Collect. Where POST /v3/collection_orders creates a collection order once, this endpoint is designed to be called repeatedly with the current outstanding state: it creates the collection order when it does not exist yet, updates its invoices when the outstanding amount changed, and closes it when nothing is outstanding anymore. The debtor must already exist. Create or update it via the /v3/debtors endpoints first; when a new collection order is created, the debtor's contact information is copied onto it. ### Matching The entry is matched to an open collection order (status active, pause, settlement, payment_promised or merged) by debtor_number + payment_reference. When several open collection orders share that combination, the most recent one is used. ### Reconciliation outcomes The outstanding amount of the request (sum of all eligible invoice amounts) is compared to the known amount of the matched collection order: | Situation | Behaviour | action | events | |-----------|-----------|----------|----------| | No match, amount > 0 | Collection order created | created | N1 (or NP1 when created paused) | | No match, amount <= 0 or no eligible invoices | Nothing happens | skipped | - | | Equal | Nothing changes | unchanged (or status_updated) | CS1 | | Zero or negative | Collection order closed as paid, paylink messages closed | closed | PF0 | | Higher | Invoice lines replaced with the submitted set | updated | CI1 | | Lower | Payment/credit lines added per invoice; invoices missing from the request are removed | updated | PP1 (or PP2 when an invoice was removed) | The events array lists every collection sync event this request logged, in order. On top of the amount event above it can contain SA1/SP1/SW1 when the flow status changed, and PR1 for every submitted invoice that was ignored because it was paid within the respite window. During an active settlement or payment promise the specific events listed under Settlements and Payment promises below are logged instead of the generic ones. ### Flow status The optional flow_status field (active, pause, withdraw) is applied to the matched collection order and adds event SA1, SP1 or SW1 to the response. Status changes can be disabled per client with the collectionsync_disable_status_sync client setting. ### Payment modules The optional payment_modules field replaces the payment modules of the matched or created collection order, just like PATCH /v3/collection_orders/{id}: listed modules are enabled, all others are disabled, and an empty array disables all of them. When the field is omitted or null, a newly created collection order gets the default payment modules configured for your environment, and an existing collection order keeps its payment modules. Skipped requests never change payment modules. ### Flow start A newly created collection order starts at step 1 of the flow configured in the start_flow_id client setting. The first flow step is scheduled one hour after the request, so a later sync of the same debtor and payment reference is always processed before the first step of the flow runs. ### Eligibility of invoices Client settings control which submitted invoices are picked up: - collectionsync_pick_up_date + collectionsync_pick_up_date_delay: invoices whose invoice date (or due date) is younger than the delay are not yet eligible. - collectionsync_payment_respite: invoices that were paid within the respite window are ignored (event PR1). ### Settlements Collection orders with an active settlement are reconciled against the invoice total excluding recent payments, and settlement terms are updated asynchronously. The amount events are replaced by their settlement-specific variants: | Situation | Behaviour | action | events | |-----------|-----------|----------|----------| | Equal | Nothing changes | unchanged (or status_updated) | CSS1 | | Zero or negative | Collection order closed as paid | closed | PFS0 | | Higher | Invoice lines replaced, settlement cancelled | updated | CIS1 | | Lower, nothing changed since the previous sync | Nothing changes | updated | CSS1 | | Lower, paid amount equals the next installment | Payment/credit lines added | updated | PTF1 | | Lower, paid amount less than the next installment | Payment/credit lines added | updated | PTP1 | | Lower, paid amount more than the next installment | Payment/credit lines added | updated | PTF2 | When flow_status pause or withdraw is applied while a settlement is active, the settlement is cancelled and event SPS1 or SWS1 is logged instead of SP1 or SW1. Requests for a debtor and payment reference with a legacy (pre-settlement) payment arrangement are rejected with a 422 response. ### Payment promises Collection orders with an active payment promise are reconciled against the invoice total excluding recent payments, and the promise is updated asynchronously: payments count towards the promised amount, and the promised amount is lowered when it would exceed the outstanding amount. The amount events are replaced by their promise-specific variants: | Situation | Behaviour | action | events | |-----------|-----------|----------|----------| | Equal | Nothing changes | unchanged (or status_updated) | CSP1 | | Zero or negative | Collection order closed as paid, promise fulfilled | closed | PFP0 | | Higher, profile breaks the promise on increase | Invoice lines replaced, promise broken and its fallout/follow-up strategy executed | updated | CIP1 | | Higher, profile lets the promise continue | Invoice lines replaced, promise continues | updated | CIP2 | | Lower, nothing changed since the previous sync | Nothing changes | updated | CSP1 | | Lower, paid amount equals the outstanding promised amount | Payment/credit lines added, promise fulfilled and its follow-up strategy executed for the remaining balance | updated | PPF1 | | Lower, paid amount less than the outstanding promised amount | Payment/credit lines added | updated | PPL1 | | Lower, paid amount more than the outstanding promised amount | Payment/credit lines added, promise fulfilled and its follow-up strategy executed for the remaining balance | updated | PPM1 | When flow_status pause or withdraw is applied while a payment promise is active, the promise is cancelled and event SPP1 or SWP1 is logged instead of SP1 or SW1. ### Response fields | Field | Description | |-------|-------------| | action | What the sync did: created, updated, closed, unchanged, status_updated or skipped | | collection_order_id | The matched or created collection order, when there is one | | events | The collection sync events logged by this request, in order | ### Rate limit Each sync request costs 1 point. See the *Rate limiting* section at the top of this documentation for how the shared limit works.