Acumatica and Zuora integration

What moves between them

The main flow runs from Zuora into Acumatica. After each billing run, ml-connector reads posted Zuora invoices, payments, and credit memos and posts them into Acumatica as AR invoices, payments, and GL journal transactions, mapped to the correct Acumatica GL accounts. Billing accounts move the same direction so the Acumatica customer master reflects new and changed Zuora accounts. Reference data such as currencies and account mappings is aligned so each billing document lands on a valid Acumatica account. Posted GL and AR documents are not written back into Zuora, which remains the subscription billing system of record.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the Zuora side it runs the client-credentials grant against the tenant base URL for the customer region, then caches and reuses the one-hour bearer token so it does not trip the lower AUTH rate limit, refreshing it shortly before expiry. On the Acumatica side it accepts the full tenant URL per customer and the exact endpoint version, then wraps every field value as a JSON value object so Acumatica does not reject the payload with HTTP 400. It subscribes to Zuora callout notifications for Invoice Posted, Payment Processed, and credit memo events; because a callout carries only an object id, it re-fetches the full record from Zuora before posting, and where an HMAC header is configured it verifies the signature first. Zuora payment notifications fire for electronic payments only, so external or manual payments are picked up on a scheduled poll instead. Zuora accounts map to Acumatica customers and posted Zuora invoices map to Acumatica AR invoices and journal lines on mapped GL accounts. Both APIs return HTTP 429 under load, so ml-connector reads Zuora rate-limit headers and backs off against Acumatica license limits. Zuora accepts an idempotency-key on writes, while Acumatica has none, so ml-connector checks for an existing document by natural key before creating and deduplicates callout ids. Every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A B2B software company with around 200 employees bills several thousand customers through Zuora on monthly and annual subscriptions, and runs Acumatica for finance and accounting. Before the integration, the finance team exported invoice and payment registers from Zuora each period and re-keyed the revenue totals into Acumatica by hand, then spent the first days of close chasing differences between billed revenue in Zuora and the AR and GL balances in the ledger. With Acumatica and Zuora connected, each billing run's posted invoices, payments, and credit memos flow into Acumatica automatically against the right GL accounts, and account changes keep both customer masters aligned. Close starts with revenue and AR already reconciled, and the manual re-keying step is gone.

What you can do

• •Post Zuora invoices and payments into Acumatica as AR invoices and GL journal transactions after every billing run.
• •Keep the Acumatica customer master aligned with new and changed Zuora billing accounts.
• •Bring Zuora credit memos into Acumatica so adjustments reach the ledger, where the Invoice Settlement feature is enabled.
• •Bridge Zuora client-credentials OAuth and Acumatica OAuth against the correct version-locked endpoint, with field values wrapped as Acumatica requires.
• •Trigger on Zuora HMAC callout notifications with event re-fetch, or poll on a schedule, with retries and a full audit trail on every record.

Questions

Which direction does data move between Acumatica and Zuora?

The main flow is Zuora into Acumatica. Posted invoices, payments, and credit memos move from Zuora into Acumatica as AR invoices and GL journal entries, and billing accounts flow the same direction to keep the customer master aligned. Zuora stays the subscription billing system of record, so ml-connector does not write posted ledger documents back into Zuora.

How does the integration handle Zuora callout notifications and their minimal payload?

Zuora callout notifications usually carry only the event object id, not the full record. ml-connector verifies the HMAC signature where it is configured, then re-fetches the invoice, payment, or credit memo from Zuora by id before posting anything to Acumatica. Callout ids are deduplicated, and because payment notifications fire for electronic payments only, external payments are caught on a scheduled poll instead.

How does ml-connector deal with Zuora token reuse and Acumatica version-locked endpoints?

Zuora bearer tokens expire after one hour and the token endpoint has a strict per-IP limit, so ml-connector caches and reuses each token and refreshes it just before expiry rather than requesting one per call. On the Acumatica side it accepts the full tenant URL and the exact endpoint version per customer, since a mismatched version returns HTTP 404, and because Acumatica has no idempotency-key header it checks for an existing document by a natural key before creating one.