Microsoft Dynamics 365 F&O and Cleo integration

What moves between them

The flow runs in both directions through Cleo. Outbound, ml-connector reads confirmed purchase orders from Microsoft Dynamics 365 F&O and uploads them as files into the right Cleo folder, where Cleo transforms and routes an X12 850 to the supplier. Inbound, ml-connector polls Cleo mailbox folders for files a trading partner sent, such as supplier invoices arriving as X12 810 documents, and posts them into Dynamics as vendor invoice headers and lines, with the header created before its lines. Vendor and item references are aligned so each inbound line resolves to a real Dynamics vendor account and item number. The general ledger stays in Dynamics, since Cleo holds no GL records, so ml-connector never writes ledger entries into Cleo.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the Dynamics side it requests an Entra ID client credentials token scoped to the environment host, reissues it before the roughly hourly expiry, and accepts the full tenant environment URL per customer since there is no shared address; multi-entity reads add cross-company and a dataAreaId filter. On the Cleo side it exchanges username and password for an opaque bearer token, refreshes on a 401, and uploads files to a folder with a Content-Disposition filename. Because Cleo is pull-based, inbound documents are picked up by polling folder children on a schedule rather than waiting for a push, though a CIC Studio flow can also call ml-connector when a file lands. Outbound, ml-connector can use a Dynamics Business Event such as purchase order confirmed as a trigger, then fetch the full order over OData before uploading it. Cleo has no idempotency key and re-uploading a file creates a duplicate, so each upload uses a unique filename and inbound files are deduped on the Business Event ControlNumber and a BullMQ jobId before posting to Dynamics, which has its own natural-key duplicate check on vendor invoices. Cleo rate limits at about five requests per second per API path and Dynamics returns HTTP 429 with a Retry-After header, so ml-connector backs off and retries, with automatic retries, a full audit trail, and error replay on every record.

A real-world example

A mid-sized consumer goods manufacturer with roughly 600 employees runs Microsoft Dynamics 365 F&O for procurement and finance and trades EDI with a handful of large retail customers and suppliers through Cleo. Before the integration, a coordinator exported confirmed purchase orders from Dynamics and dropped them into Cleo by hand, then printed inbound supplier invoices Cleo received and keyed them back into Dynamics, which delayed orders and left invoice data prone to typos. With Microsoft Dynamics 365 F&O and Cleo connected, each confirmed order is uploaded to Cleo for routing as an 850 within the polling window, and inbound 810 invoices post into Dynamics as vendor invoices matched to the right vendor and item. Orders reach suppliers sooner, the keying errors are gone, and the AP team works from records that already match what the partner sent.

What you can do

• •Upload confirmed Microsoft Dynamics 365 F&O purchase orders into Cleo folders for routing to suppliers as X12 850 documents.
• •Poll Cleo mailbox folders for inbound files and post supplier invoices arriving as X12 810 into Dynamics as vendor invoice headers and lines.
• •Align Dynamics vendor accounts and item numbers so every inbound EDI line resolves to a real record.
• •Bridge Entra ID OAuth client credentials on Dynamics with the Cleo password-grant bearer token, reissuing each before expiry.
• •Dedupe on the Business Event ControlNumber and unique upload filenames, with retries and a full audit trail on every record.

Questions

Which direction does data move between Microsoft Dynamics 365 F&O and Cleo?

It moves both ways through Cleo. Confirmed purchase orders go from Dynamics into Cleo folders for routing to suppliers as X12 850 documents, and inbound files Cleo receives, such as supplier invoices as X12 810, are posted into Dynamics as vendor invoice headers and lines. Cleo holds no general ledger records, so the GL stays in Dynamics and ml-connector never writes ledger entries into Cleo.

Cleo has no invoice or purchase order records, so how does the mapping work?

Cleo is a B2B and EDI platform, so business documents travel through it as X12 EDI files rather than as native resources. ml-connector reads purchase orders from the Dynamics OData entities and uploads them as files to a Cleo folder, where Cleo transforms and routes them, and it downloads inbound EDI files from Cleo and maps the 810 fields onto Dynamics vendor invoice headers and lines. The folder and file REST API is what Cleo exposes, so the connector maps Dynamics entities to and from those payloads.

Does Cleo push files, or does ml-connector poll for them?

Polling is the default because Cleo is primarily pull-based and has no self-service webhook subscription API. ml-connector polls Cleo folder children on a schedule to pick up inbound documents, and uploads outbound documents to folders the same way. A Cleo admin can configure a CIC Studio flow to call ml-connector when a file lands, but the connector keeps polling as the reliable path so nothing is missed if a push is not set up.