Acumatica and TaxJar integration

What moves between them

The main flow runs from Acumatica into TaxJar. After a sales invoice is released in Acumatica, ml-connector reads it and posts it to TaxJar as an order transaction, carrying the ship-from and ship-to addresses, amount, shipping, sales tax, and line items. Credit memos move the same direction and post as TaxJar refund transactions linked back to the original order. Nexus regions flow the other way: ml-connector pulls the merchant's filing states from TaxJar periodically so Acumatica-side reporting reflects where tax is owed. TaxJar has no AP, purchase order, or GL resource, so ml-connector never writes financial entries back into Acumatica.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the Acumatica side it requests and refreshes an OAuth 2.0 bearer token, or holds a session cookie, against the customer's tenant URL, and it pins the endpoint version in every path because a mismatched version returns a 404. It builds each request body with the value-wrapped field format Acumatica requires and reads the customer's TaxZone so tax is reported against the correct jurisdiction. On the TaxJar side it sends the API token in the Authorization header and pins x-api-version. Because TaxJar has no inbound webhook and Acumatica push notifications are not guaranteed, ml-connector polls Acumatica SalesInvoice records on a LastModifiedDateTime high-water mark and posts only finalized, released invoices, since states receive this data directly. Neither system has a native idempotency header, so it uses the Acumatica ReferenceNbr as the TaxJar transaction_id and follows TaxJar's upsert rule, falling back from POST to PUT on a 422 and from PUT to POST on a 404, with a BullMQ jobId to dedup a re-read invoice. It always sends a shipping value, even zero, and reports zero-tax orders, because both are TaxJar requirements. Acumatica rate limits return HTTP 429 and start throttling at half the licensed request rate, so ml-connector backs off with jitter and respects the concurrent-session limit. Every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A mid-sized online retailer with about 150 staff runs Acumatica Cloud ERP for order billing, inventory, and finance, and ships to customers in twenty states. Before the integration, an accountant exported invoices from Acumatica each week and uploaded them into TaxJar by hand, which meant some sales never got reported, refunds were missed, and the state filings never quite matched the sales recorded in the ledger. With Acumatica and TaxJar connected, every released sales invoice posts to TaxJar within the polling window with its real ship-to address and line items, credit memos post as refunds, and the nexus list stays current. The manual upload is gone and the monthly filings reconcile against Acumatica without a scramble.

What you can do

• •Report released Acumatica sales invoices to TaxJar as order transactions for state tax filing.
• •Post Acumatica credit memos to TaxJar as refund transactions linked to the original order.
• •Use the Acumatica ReferenceNbr as the TaxJar transaction_id with upsert dedup so an invoice is never double-reported.
• •Authenticate Acumatica with OAuth 2.0 or session login and TaxJar with its API token, pinning the Acumatica endpoint version.
• •Pull TaxJar nexus regions on a schedule and poll Acumatica on a high-water mark, with retries and a full audit trail on every record.

Questions

Which direction does data move between Acumatica and TaxJar?

The main flow is Acumatica into TaxJar. Released sales invoices and credit memos move from Acumatica into TaxJar as order and refund transactions for compliance reporting. Nexus regions are pulled back from TaxJar so reporting reflects where tax is owed. TaxJar has no AP, purchase order, or GL resource, so ml-connector never writes financial entries back into Acumatica.

How does the integration avoid reporting the same Acumatica invoice twice?

TaxJar identifies transactions by a unique transaction_id rather than an idempotency header. ml-connector uses the Acumatica invoice ReferenceNbr as that transaction_id and follows TaxJar's upsert rule, falling back from POST to PUT when a 422 says the record exists and from PUT to POST on a 404. A BullMQ jobId adds a second layer of dedup so a re-read invoice is updated, not duplicated.

Does Acumatica push invoices to TaxJar, or does ml-connector poll for them?

ml-connector polls. Acumatica can send Push Notifications, but they retry only a few times with no dead-letter queue and are not guaranteed, and TaxJar publishes no inbound webhook at all. So ml-connector reads Acumatica SalesInvoice records on a LastModifiedDateTime high-water mark and posts finalized invoices to TaxJar on the schedule you set, which also avoids reporting an invoice before it is released.