FreshBooks and SPS Commerce integration

What moves between them

Invoices and bills from FreshBooks flow outbound into SPS Commerce as invoice and ASN documents, tagged with the retail trading partner ID so they reach the correct buyer. Purchase orders and shipment advice flow inbound from SPS Commerce partners back into FreshBooks as bill line items and events, so your accounting reflects what the retailers ordered and shipped. Polling runs on a customer-defined schedule, typically every 5 to 15 minutes. Webhook payloads from FreshBooks trigger immediate processing, but bill and invoice updates are also synced on poll to catch any misses.

How ml-connector handles it

ml-connector holds both credential sets. For FreshBooks, it stores the OAuth bearer token and refreshes it if a call returns 401. For SPS Commerce, it uses client credentials to obtain a JWT bearer token on each poll cycle and refreshes on 401. Outbound records from FreshBooks are transformed into RSX 7.7.7 JSON envelope format and routed to the correct SPS Commerce trading partner using the partner ID. Inbound purchase orders are polled via cursor-based pagination and mapped into FreshBooks bill lines. Because SPS Commerce has no idempotency guarantee, ml-connector tracks document-level identifiers (purchase order number, invoice number) and deduplicates on re-poll. Rate limits from SPS Commerce (HTTP 429) trigger exponential backoff. Every record carries full tracing so a failed sync can be inspected and replayed.

A real-world example

A small-to-midsize business manufactures components and sells to national retail chains via a distributor. Before the integration, the finance team manually exported invoices from FreshBooks, converted them to EDI format, and uploaded them via SFTP to SPS Commerce, then monitored an AS2 mailbox for purchase orders and re-entered them into FreshBooks as payables. With FreshBooks and SPS Commerce connected, invoices publish automatically when booked in FreshBooks, and retail purchase orders land in FreshBooks as bills ready for matching to POs, cutting the manual re-entry and SFTP overhead by 80 percent.

What you can do

• •Push FreshBooks invoices and bills into SPS Commerce in RSX format, routed to the correct trading partner.
• •Ingest purchase orders from SPS Commerce retail partners and sync them into FreshBooks as payable bills.
• •Authenticate FreshBooks with OAuth user delegation and SPS Commerce with OAuth client credentials, handling token refresh and 401 retries.
• •Poll SPS Commerce on a schedule with cursor-based pagination and deduplicate on document identifiers to prevent duplicate syncs.
• •Track every record with full audit context and allow manual replay if a downstream sync fails.

Questions

How does the integration handle FreshBooks' user-delegated OAuth and SPS Commerce's client credentials OAuth?

ml-connector stores both credential sets encrypted. FreshBooks requires a user to authorize once; ml-connector then refreshes the OAuth bearer token if a call returns 401. SPS Commerce uses a standard client credentials flow; ml-connector obtains a JWT bearer token on each poll cycle and refreshes on 401 from the token endpoint.

What is the RSX envelope format, and why do invoices need it?

RSX 7.7.7 is a JSON wrapper that SPS Commerce uses to envelope all documents flowing to retail trading partners. Instead of sending raw invoice fields, ml-connector wraps each FreshBooks invoice in RSX format and includes the trading partner ID so the invoice routes to the correct retailer.

How does the integration prevent duplicate syncs of purchase orders from SPS Commerce?

SPS Commerce has no built-in idempotency mechanism, so ml-connector tracks document-level identifiers (purchase order number, invoice number) in its audit log. On each poll, it checks the identifier against prior syncs and skips records already processed, preventing duplicate bill creation in FreshBooks.