QuickBooks Desktop and SPS Commerce integration

What moves between them

Inbound purchase orders arrive at SPS from retail trading partners and are read via poll from the /fulfillment/v1/purchaseorders endpoint every 5-15 minutes. Each order is mapped into a QuickBooks Bill or PurchaseOrder and inserted into the accounting system with vendor and line-item details intact. Outbound bills and supplier invoices from QuickBooks are read via QBWC polling on the same interval, transformed into SPS invoice documents (810) wrapped in RSX format, and posted back to SPS for transmission to the retail partners. Vendor and customer master data such as account numbers and cost codes are synchronized bidirectionally so line-item allocations land on valid accounts in both systems.

How ml-connector handles it

ml-connector hosts the SOAP endpoint that QBWC calls and manages the session-token handshake on each poll interval. On the QuickBooks side, it uses ModifiedDateRangeFilter to detect new or changed bills and purchase orders since the last poll, re-queries for the current EditSequence before any modification, and retries on SOAP faults using exponential backoff. On the SPS side, ml-connector obtains a fresh OAuth bearer token before each API call, maintains cursor state across paginated responses from /fulfillment/v1/purchaseorders, and wraps all outbound documents in the RSX 7.7.7 envelope before posting. Because QuickBooks has no idempotency mechanism, ml-connector deduplicates using a combination of PO number and vendor ID, and because SPS rate limits are undocumented, ml-connector implements exponential backoff with jitter on 429 responses. Every sync operation is logged with source and target IDs, timestamps, and field mappings so failed records can be replayed after corrections are made.

A real-world example

A regional grocery distributor uses QuickBooks Desktop to manage vendor invoices and purchase orders from suppliers and SPS Commerce to distribute products to Walmart, Target, and Amazon via EDI. Before integration, purchase orders arrived from retailers as EDI files dropped into SFTP, and the finance team manually entered them into QuickBooks, then exported supplier invoices to a separate file and uploaded them back to SPS for retailer transmission. Reconciliation took two days per week because PO numbers and line items had to be verified across three systems. With QuickBooks and SPS connected, inbound orders land in QuickBooks automatically with full vendor and line-item context, and outbound invoices are posted to SPS immediately on creation. The purchasing team now works from a single source of truth, and reconciliation happens in hours.

What you can do

• •Sync inbound EDI purchase orders from SPS Commerce into QuickBooks Desktop as Bills and PurchaseOrders with vendor and line-item details.
• •Post QuickBooks vendor invoices and bills back to SPS Commerce in EDI 810 format wrapped in RSX 7.7.7 envelope for transmission to retail trading partners.
• •Maintain vendor and customer master data in sync across both systems so purchase orders and invoices land on the correct accounts.
• •Authenticate QuickBooks via SOAP session token from the customer's QBWC agent and SPS via OAuth 2.0 client credentials with JWT bearer tokens.
• •Poll both systems on a configurable interval with change detection, deduplication, and exponential backoff on rate limits, with full audit trail on every record.

Questions

How does the integration handle QuickBooks Desktop's local polling requirement?

QuickBooks Desktop has no webhooks; all integrations must call a customer-hosted SOAP endpoint from the QuickBooks Web Connector (QBWC) agent. ml-connector hosts that SOAP service, handles the session-token handshake that QBWC provides, and polls both QuickBooks and SPS at a configurable interval (typically 5-15 minutes). Because QuickBooks must be open and logged into the company file for QBWC to work, this model is well-suited to businesses that keep QuickBooks running during business hours.

What happens when SPS Commerce and QuickBooks have different rate limits or outage windows?

SPS publishes no rate limits, so ml-connector implements exponential backoff with jitter on HTTP 429 responses and tracks how many times a document has been retried. QuickBooks has a SOAP timeout of roughly 60 seconds, so ml-connector breaks large queries into paginated requests. If SPS is unavailable, the next poll interval will retry. If QuickBooks is not running or logged in, QBWC will not call the service, and ml-connector will retry on the next interval. Failures are logged with full context so manual intervention can be applied if either system is down for an extended period.

Does ml-connector handle the RSX envelope format and OAuth tokens for SPS?

Yes. ml-connector obtains a fresh OAuth bearer token using the SPS client credentials before each API call and caches it until a 401 response indicates it has expired. All outbound documents are wrapped in the RSX 7.7.7 JSON envelope format required by SPS, including the correct version tag and document type codes (e.g., 810 for invoices). Inbound documents from SPS arrive already parsed, and ml-connector extracts the transaction data, unmaps it into QuickBooks field names, and inserts it as Bills or PurchaseOrders.