QuickBooks Online and SPS Commerce integration

What moves between them

Purchase orders flow from SPS Commerce into QuickBooks Online, creating or updating PurchaseOrder entities with line items mapped to QuickBooks Items and Accounts. Invoices and shipment confirmations flow outbound from QuickBooks to SPS, wrapped in RSX envelopes and routed to the correct trading partner. Reference data such as vendors and items are synchronized bidirectionally to ensure both systems stay aligned. Polling pulls inbound POs from SPS every 5-15 minutes on a configurable schedule; outbound documents are triggered immediately when created or changed in QuickBooks.

How ml-connector handles it

ml-connector stores both OAuth credential sets encrypted and manages token lifecycle on both sides: refreshing QuickBooks access tokens before they expire at the 1-hour mark, and rotating SPS bearer tokens via client credentials on each request. On inbound, it polls SPS' /fulfillment/v1/purchaseorders endpoint with cursor-based pagination, unwraps the RSX 7.7.7 envelope, and creates or updates QuickBooks PurchaseOrder entities with the correct SyncToken for concurrency control. Vendor records from each new trading partner are synced from QuickBooks to SPS during onboarding so line items route correctly. On outbound, ml-connector listens for Invoice and PurchaseOrder updates in QuickBooks via webhooks or polling, wraps the data in the RSX envelope format, and posts to the appropriate SPS endpoint for each trading partner. Because SPS has no vendor-defined idempotency, ml-connector deduplicates at the application layer using purchase order numbers and invoice numbers as unique keys. SPS rate limits are undocumented, so ml-connector backs off with exponential jitter on 429 responses. Every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A mid-size supplier manufactures products for retail distribution, managing inventory and invoicing through QuickBooks Online while serving Walmart, Target, and Amazon through SPS Commerce. Before the integration, the supply chain team manually entered purchase orders from SPS into QuickBooks, then exported invoices to upload into SPS, causing delays and transcription errors during peak seasons. Trading partners often rejected invoices due to formatting mismatches or out-of-sync line item counts. With QuickBooks and SPS connected, purchase orders flow automatically into the accounting system, invoices post immediately after shipment confirmation, and trading partner routing happens without manual intervention. Peak season throughput doubles and compliance rejections drop to near zero.

What you can do

• •Sync purchase orders from SPS Commerce into QuickBooks Online, creating and updating PurchaseOrder entities with line items and account mappings.
• •Post invoices and advance ship notices from QuickBooks to SPS Commerce, wrapped in the required RSX 7.7.7 envelope format and routed to the correct trading partner.
• •Manage OAuth 2.0 token lifecycle for both systems, including hourly refresh on QuickBooks and client credential re-authentication on SPS.
• •Deduplicate documents at the application layer and back off exponentially on SPS rate limits to ensure reliable sync across unpredictable traffic.
• •Maintain a full audit trail on every purchase order and invoice, with replay capability if a downstream system call fails.

Questions

How does ml-connector handle QuickBooks token expiration and SPS trading partner routing?

QuickBooks access tokens expire in 1 hour, and ml-connector refreshes them before expiry using the stored refresh token. SPS requires trading partner IDs (retailer identifiers) to be provisioned during onboarding, and ml-connector routes outbound invoices to the correct partner based on that configuration. Both systems use OAuth bearer tokens, which ml-connector stores encrypted and presents on every call.

Why does ml-connector need to unwrap RSX envelopes and how does deduplication work?

SPS wraps all documents in RSX 7.7.7 JSON envelopes, and the raw data sits inside that envelope. ml-connector unwraps the envelope on inbound to extract the purchase order or shipment data for QuickBooks, and wraps outbound invoices in the same RSX format for SPS. Because SPS has no idempotency mechanism, ml-connector deduplicates using purchase order numbers and invoice numbers as unique keys to prevent duplicate records if a call is retried.

What happens if a purchase order sync stalls or an SPS API call fails?

Every record in the sync pipeline carries a full audit trail with timestamps and status. If an inbound PO fails to create in QuickBooks or an outbound invoice fails to post to SPS, ml-connector retries with exponential backoff and jitter. If the failure persists, the record is logged and can be replayed manually once the issue is resolved, without losing the original data or creating duplicates.