Acumatica and Cleo integration

What moves between them

Documents move in both directions, mapped to their X12 transaction. Outbound from Acumatica, ml-connector reads new sales invoices and renders them as 810 files, and reads purchase orders as 850 files, then uploads each to the correct Cleo folder for routing to the trading partner. Inbound from Cleo, it polls the mailbox folders for EDI a partner sent, downloads the files, and writes them into Acumatica: a partner 850 becomes a sales order, an 810 becomes an AP bill against the matching vendor, and 856 and 855 acknowledgments update the related documents. Cadence is a polling schedule you set, since Cleo outbound push needs CIC Studio setup by the customer's Cleo admin.

How ml-connector handles it

ml-connector stores both credential sets encrypted and exchanges the Cleo username and password for a bearer token through the password grant, refreshing on a 401 and re-authenticating if the refresh also fails. On the Acumatica side it accepts the full instance URL and the exact endpoint version per customer, since a mismatch returns 404, and wraps every field value in the required value object so writes do not fail with a 400. Each Acumatica entity is mapped to its EDI transaction before any file moves, so a sales invoice becomes a valid 810 and a purchase order a valid 850. Because Cleo has no idempotency key and a re-uploaded file creates a duplicate, every upload gets a unique filename with a timestamp so a document is never processed twice, and inbound files are tracked by name so the same file is not imported again. Cleo rate-limits at five requests per second per API path and Acumatica returns 429 under load, so ml-connector backs off with jitter, and failed records are kept with a full audit trail for replay. If the Cleo account has TOTP two-factor enabled, a dedicated service account without 2FA is recommended, since a machine cannot supply a fresh code on every call.

A real-world example

A mid-sized food distributor with around 250 employees runs Acumatica Cloud ERP for purchasing, inventory, and finance, and its largest grocery customers require EDI through a Cleo Integration Cloud mailbox. Before the integration, a clerk rekeyed each customer's 850 purchase order from a Cleo folder into Acumatica as a sales order by hand, and exported finished invoices to send back as 810 files, which was slow and produced chargebacks when a number was mistyped. With Acumatica and Cleo connected, inbound 850 files become Acumatica sales orders automatically and posted invoices flow out as 810 files to each partner mailbox. Orders enter the system the day they arrive, the rekeying is gone, and EDI compliance penalties drop.

What you can do

• •Render Acumatica sales invoices as X12 810 files and upload them to the Cleo trading-partner mailbox.
• •Turn inbound 850 purchase order files from Cleo folders into Acumatica sales orders, and 810 files into AP bills.
• •Map each Acumatica entity to its EDI transaction so documents leave and arrive in a format the partner accepts.
• •Bridge Cleo's OAuth2 password grant and tenant subdomain with Acumatica's version-locked OAuth tenant login.
• •Give every file a unique timestamped name and track imports so no document is processed twice, with full audit and replay.

Questions

Which direction does data move between Acumatica and Cleo?

Both directions, each mapped to an EDI transaction. Acumatica sales invoices and purchase orders go out through Cleo as 810 and 850 files for routing to a trading partner, and inbound EDI that Cleo received is pulled into Acumatica as sales orders, AP bills, and customers. The cadence is a polling schedule you set.

Cleo has no invoice or purchase order endpoint, so how does the connection work?

Cleo is integration middleware, not a finance system, so invoices and POs are not native REST objects. Its REST API manages folders and files, and business documents move through it as X12 EDI. ml-connector maps each Acumatica record to its EDI transaction, then uploads the file to the right Cleo folder to send and polls folders to retrieve what a partner sent.

How does the integration avoid duplicate documents and handle Acumatica's version-locked URL?

Cleo has no idempotency key, and re-uploading a file creates a duplicate, so ml-connector gives every upload a unique timestamped filename and tracks inbound files by name so none is imported twice. On the Acumatica side it stores the full instance URL and the exact endpoint version per customer, since a mismatch returns 404, and wraps every field value as Acumatica requires so writes do not fail with a 400.