Microsoft Dynamics 365 Business Central and Cleo integration

What moves between them

Documents move in both directions. Outbound, ml-connector reads posted sales invoices and sales orders from Microsoft Dynamics 365 Business Central and uploads them as X12 810 and 850 files into the assigned Cleo mailbox folder, where Cleo routes them to the trading partner. Inbound, it polls Cleo folders for partner files such as X12 850 purchase orders and 855 acknowledgments, downloads them, and creates or updates the corresponding sales orders and status in Business Central. Reference data such as items and customers is read from the ERP so EDI lines reference valid records. Cleo holds no financial source data, so ml-connector never treats Cleo as a system of record; it only moves files and reads back what partners send.

How ml-connector handles it

ml-connector stores both credential sets encrypted and runs two token flows side by side: the Microsoft Entra client-credentials token for Business Central, refreshed on a 401, and the Cleo password-grant Bearer token, refreshed through the Cleo refresh endpoint and re-authenticated if that fails. Because Cleo has no programmatic webhook subscription API and is pull-based, inbound documents are picked up by polling Cleo folder contents on a schedule rather than waiting for a push. On the Business Central side it can subscribe to webhooks for sales invoices and sales orders, but since those notifications carry no payload it fetches the changed record before building the EDI file, and it polls for purchase orders because they are not webhook-supported. Business documents are mapped to and from raw X12 transactions, since Cleo exposes files rather than invoice fields. Each uploaded file uses a unique name to avoid duplicate processing, since Cleo has no idempotency key, and BullMQ jobs are keyed on the Business Central document number so the same document is not enqueued twice. Cleo rate limits per endpoint return HTTP 429 and Business Central throttles per environment, so both calls back off and retry, and every record carries a full audit trail and can be replayed.

A real-world example

A mid-sized consumer goods distributor runs Microsoft Dynamics 365 Business Central for sales, inventory, and finance, and trades with several large retail buyers that require EDI through a partner already onboarded in Cleo. Before the integration, a clerk printed each retail purchase order that arrived in the Cleo mailbox, keyed it into Business Central as a sales order by hand, and later exported the matching invoice and re-uploaded it as an EDI file, which delayed orders and produced keying errors during busy periods. With Business Central and Cleo connected, inbound 850 purchase orders become sales orders automatically and posted invoices flow back out as 810 files to the same partner. Order entry no longer waits on manual typing, and the EDI files going to retailers match the orders in the ERP.

What you can do

• •Upload posted Business Central sales invoices and sales orders to Cleo mailbox folders as outbound X12 EDI files.
• •Poll Cleo folders for inbound X12 850 purchase orders and create matching sales orders in Business Central.
• •Read inbound 855 acknowledgments from Cleo and update order status in the ERP.
• •Bridge Business Central Microsoft Entra client credentials and Cleo OAuth password-grant tokens on every call.
• •Use unique file names and document-keyed jobs to prevent duplicates, with retries and a full audit trail.

Questions

Why does the integration move EDI files instead of invoice or purchase order records on the Cleo side?

Cleo Integration Cloud is B2B and EDI middleware, not a finance system, so its REST API manages folders, files, and connections rather than invoices or purchase orders. Business documents flow through Cleo as X12 EDI files in mailbox folders. ml-connector therefore uploads and downloads files to those folders and maps each file to and from the matching Business Central record.

How are credentials handled across the two systems?

Microsoft Dynamics 365 Business Central uses OAuth 2.0 client credentials through Microsoft Entra ID with an Azure app registration, while Cleo uses OAuth 2.0 password grant that returns a Bearer token. ml-connector stores both credential sets encrypted and runs each token flow independently. The Business Central token refreshes on a 401, and the Cleo token refreshes through its refresh endpoint, falling back to a full re-authentication if needed.

Does Cleo push new files to the connector, or does the connector poll?

Cleo has no public webhook subscription API and is primarily pull-based, so ml-connector polls Cleo folder contents on a schedule to pick up inbound files. Outbound push from Cleo is possible only when a Cleo administrator configures an HTTP action inside a flow in CIC Studio. The standard pattern remains uploading files to trigger outbound EDI and listing folders to retrieve inbound documents.