Creates a CollectionOrder resource.

This endpoint allows you to create a new collection order for a debtor. A collection order contains a customer's contact information and one or more invoices to be collected. A flow with pre-specified actions will start at the designated time. The response contains our unique identifier for this collection order: collection_order_id. It is recommended that you store the collection_order_id in your system for future API calls. ### Field validation Most contact and address fields are optional at submission. Whether a field is actually needed depends on the configured action in the flow step that runs for this order — address fields are needed for letters, an email address for email reminders, a phone number for SMS, and so on. If a required field is missing when the action would run, the flow falls back to the back-up step configured on the flow instead of executing that action. ### 1. Identification information Within the identification information category, we list data that is essential for bundling requests. The Collect portal utilizes several layers to aggregate information. The primary grouping level is the Client ID, which may represent a production or testing environment. Subsequently, data is organized by Batch ID, followed by Debtor Number, and finally by Payment Reference. Without a proper setup of this identification information, collection orders may be difficult to trace and monitor within the platform. | Field | Description | Usage | |-------|-------------|-------| | debtor_number | Identifier for a debtor, e.g. a customer number | required | | payment_reference | Identifier for the payment request | required | | concerning | The subject of the payment request. If you are collecting an invoice for another company, specify the company name here. | optional | | label | A free-form label for categorizing this collection order. Can also be used as a merge variable within communications. | optional | | batch_id | Your identifier for a group of requests. If not provided, it is auto-generated as Flow_YYYYMMDD_{flow_id}. | optional | | client_request_id | Your unique identifier for this single request | optional | | username | Name of employee making this request. Useful for tracking employee performance when making single requests. | optional | ### 2. Flow information For starting a collection order it should be sent towards a specific flow_id and flow_step, these are the configurations that are done within the Collect portal. If a default flow is set up for your environment in Collect, flow_id and flow_step may be omitted: the collection order then starts in that flow at step 1. Without a default flow both fields are required. They always have to be provided together; providing only one results in a validation error. The flow_datetime field controls when the flow starts: - If omitted and the current time is before 09:00, the flow is scheduled for today at 09:00 - If omitted and the current time is 09:00 or later, the flow starts immediately - If a past datetime is provided, the flow starts immediately - If a future datetime is provided, the flow is scheduled for that time | Field | Description | Usage | |-------|-------------|-------| | flow_id | The ID of the starting flow. The Flow ID can be obtained from the application administrator responsible for the configuration. | required, unless a default flow is set up for your environment | | flow_step | The step-number where the flow should start. Default to step 1. Rarely is it a higher step. | required, unless a default flow is set up for your environment | | flow_datetime | The date and time a flow is started for this collection order. | optional | ### 3. Customer information Within the fields below the customer's basic details are listed. These fields can be either used within communications or within flow configurations. | Field | Description | Usage | |-------|-------------|-------| | first_name | First name of the debtor | optional | | last_name | Last name of the debtor | required | | company_name | Name of debtor's business. Is used in the address of letters. | optional | | personal_identification_number | National identification number of the debtor (e.g. BSN, social security number). | optional | | date_of_birth | Date of birth of debtor (format: YYYY-MM-DD). | optional | | gender | Gender of debtor. M = male, F = female. | optional | | language | Language of debtor. If available the payment pages and messages will be in the debtor's preferred language (e.g. nl, de, fr, en). | optional | ### 4. Contact information The customer's contact details are listed below. | Field | Description | Usage | |-------|-------------|-------| | email | Email address of the debtor | optional | | secondary_email | Secondary email address of the debtor | optional | | phone_number | Telephone number of debtor. Preferably with country code; if omitted we will add it based on your country. | optional | | secondary_phone_number | Secondary telephone number of debtor | optional | | street_name | Street name | optional | | house_number | House number | optional | | zip_code | Postal code | optional | | city | City | optional | | country | Country of debtor | optional | | secondary_street_name | Second address. Will not be used for letters. Could be used for informational purposes, for instance a delivery address. | optional | | secondary_house_number | Second address house number | optional | | secondary_zip_code | Second address postal code | optional | | secondary_city | Second address city | optional | | secondary_country | Second address country | optional | ### 5. Variables (free variables) Collect offers up to 500 free variables that can be utilized for specific use cases, such as deviating to specific flows or for use within communication. Within Collect, variables 1 through 5 are designated as 'high-performance' variables. This means they have direct accessibility within specific configurations across our platform (including but not limited to payment profiles or Peppol configurations) and also hold a more prominent position within the user interface. We recommend starting the mapping process at variable 6. Reserve variables 1 through 5 for critical data points identified after the full mapping is complete. Additionally, we advise having your mapping validated by a Collect specialist to ensure adherence to best practices. The variables field accepts key-value pairs from variable1 through variable500. Variables 1–5 have a maximum length of 100 characters. Variables 6–500 have a maximum length of 50.000 characters. ### 6. Payment modules Collect supports various payment methods, which are typically configured within the Collect Portal. We strongly recommend using the Portal for this configuration to fully utilize the flexibility of payment profiles and flows. While it is possible to enforce specific methods per API request, this is optional. If no payment modules are provided in the request body, the system will default to the methods configured in the Portal. Supported payment modules are: - ideal - credit_card - bancontact - emandate_one_off - emandate_recurring - bank_transfer - paypal - sofort - pay_safe_card - ubl - giropay - psd2 - in3 - via_cash - apple_pay - amazon_payment - pay_by_bank - carte_bancaire - bancontact_ocp - start_token_recurring - start_token_paymentplan - google_pay - bizum Note: The payment modules emandate_one_off and emandate_recurring cannot be used together. | Field | Description | Usage | |-------|-------------|-------| | payment_modules | Array of payment module identifiers to enable for this collection order | optional | | return_url | The customer is redirected to this URL after the payment process has been completed. | optional | ### 7. Financial data (invoices) A collection order must contain at least 1 and at most 500 invoices. For flow types that collect money (invoice, recurring, reminder), the combined amount of all invoices must be greater than 0. - Some payment methods require a minimum/maximum amount in order for a payment to be completed. Please check this with your PSP. - The due_date parameter only has an informational purpose. The actual due date of a message is determined within the flow configuration. - If date is not provided for an invoice, it defaults to today. | Field | Description | Usage | |-------|-------------|-------| | number | Name or number of the invoice | required | | date | Date of the invoice | optional | | description | Description of the invoice | required | | amount | Amount of the invoice in cents | required | | due_date | Date when invoice is due. This parameter has a cosmetic function only and is not the same as the message due date. | optional | | type | Invoice type: principal, payment, collection_costs, vat, interest, transaction_costs, credit, payment_difference, other | optional | | description2 / description3 | Additional description fields | optional | | amount2 / amount3 | Additional amount fields in cents | optional | | quantity | Quantity for this invoice line. May be negative to express a correction/credit line. | optional | ### 8. Document (optional) Optionally, a PDF document can be attached to the collection order by providing a document object. The document will be encrypted and stored, and automatically linked to the created collection order. | Field | Description | Usage | |-------|-------------|-------| | document.file_name | File name, must end with .pdf | required | | document.content | Base64-encoded PDF file | required | | document.description | Description of the document | optional | | document.visible_for_customer | Whether the document is visible to the customer (default: true) | optional | ### Rate limit A collection order without a document costs 1 point; a collection order with a document costs 40 points. See the *Rate limiting* section at the top of this documentation for how the shared limit works. ### Example requests - Download example - Invoice with details - Download example - Rent - Download example - Utilities - Download example - Insurance - Download example - Debt collection - Download example - Financial year