Which direction does data move between FreshBooks and BigCommerce?

It runs mainly from BigCommerce into FreshBooks. Paid orders, their transactions, refunds, customers, and products move from BigCommerce and become FreshBooks invoices, recorded payments, clients, and items. The chart of accounts and tax mapping stay on the FreshBooks side, and BigCommerce never receives GL data because it has no accounting objects to hold it.

How does the integration avoid recording an order twice without an idempotency key?

Neither FreshBooks nor BigCommerce exposes an idempotency-key header. ml-connector reuses the BigCommerce order number as the FreshBooks invoice number, checks FreshBooks for that number before creating, and dedupes on a BullMQ jobId. Supplying the invoice number also sidesteps the 409 conflict FreshBooks raises when invoices are created concurrently without one.

Does the integration use BigCommerce webhooks or polling?

It uses both. Signed store/order webhooks trigger the sync as soon as an order is paid, and because the payload carries only a type and id, ml-connector fetches the full order and its transactions from the REST API before posting. A scheduled poll backfills missed events, which matters because BigCommerce auto-deactivates webhooks after long inactivity or sustained delivery failures.

FreshBooksBigCommerce

FreshBooks and BigCommerce integration

FreshBooks runs invoicing, payments, and the chart of accounts. BigCommerce runs the online store, its orders, and the catalog. Connecting the two means a paid order placed in BigCommerce becomes an invoice and a recorded payment in FreshBooks without anyone re-keying it. Store customers line up with FreshBooks clients and catalog products line up with FreshBooks items, so each invoice line ties back to a known product and payer. ml-connector handles the very different auth on each side and moves the records on the schedule you set.

How FreshBooks works

FreshBooks exposes clients, invoices, payments, items, expenses, bill vendors, bills, journal entries, and the chart of accounts through its REST API at api.freshbooks.com, with JSON payloads and standard HTTP verbs. Authentication uses OAuth 2.0 authorization-code grant per user; client-credentials is not supported, and each refresh issues a new refresh token that invalidates the prior one. Almost every path needs an accountId or a numeric businessId, both read once from the /users/me identity endpoint after OAuth. Invoices created over the API start as Draft and must be marked Sent before they appear in accounting reports, and most records soft-delete by setting vis_state rather than HTTP DELETE. FreshBooks can push outbound webhooks signed with the X-FreshBooks-Hmac-SHA256 header, though delivery latency is not guaranteed, so lists are also read by offset pagination capped at 100 records per page.

How BigCommerce works

BigCommerce exposes orders, order transactions, refunds, customers, and catalog products through its REST Management API, with v2 used for order CRUD and v3 used for transactions and refunds. Authentication is a static, pre-generated access token sent in the X-Auth-Token header from a store-level API account; the token is shown once at creation and there is no Bearer prefix. Order transactions are system-generated and read-only, while orders, customers, and products support writes, and refunds must be created sequentially because the API rejects concurrent refunds on one order. BigCommerce can push signed store/order, store/customer, and store/product webhooks, but each payload carries only the resource type and id, so the full record must be fetched from the REST API. List endpoints page by cursor on v3 or page and limit on v2, with a per-plan rate quota that refreshes every thirty seconds.

What moves between them

The main flow runs from BigCommerce into FreshBooks. When a store order reaches a paid status, ml-connector reads the order and its v3 transactions and creates a matching FreshBooks invoice with line items, then records the captured payment against that invoice. BigCommerce customers flow the same direction so each invoice is tied to a FreshBooks client, and catalog products map to FreshBooks items so invoice lines reference known goods. BigCommerce refunds are read from the v3 refunds endpoint and reflected against the FreshBooks invoice and payment. The chart of accounts lives only in FreshBooks, so account and tax mapping happen on the FreshBooks side and BigCommerce never receives GL data, which it has no place to store.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the BigCommerce side it sends the static access token in the X-Auth-Token header on every request, with no Bearer prefix. On the FreshBooks side it runs the OAuth 2.0 authorization-code grant, attaches the bearer access token, and refreshes it when a call returns 401, storing the new refresh token each time because FreshBooks invalidates the previous one. Signed store/order webhooks trigger the work, and because a BigCommerce payload carries only a type and id, the full order is fetched from the v2 endpoint and its v3 transactions before anything posts; a scheduled poll backfills anything a webhook missed, since webhooks auto-deactivate after long inactivity or sustained failures. Only orders at a paid status become invoices, so unpaid and incomplete orders are skipped, and the FreshBooks invoice is created as a Draft then marked Sent so it lands in the accounting reports. Store customers are matched to FreshBooks clients and products to FreshBooks items first, so every invoice line references a record that already exists. Neither API offers an idempotency-key header, so ml-connector reuses the BigCommerce order number as the FreshBooks invoice number, checks for that number before creating, and dedupes on a BullMQ jobId, which keeps a re-read order from invoicing twice; supplying that number also avoids the 409 conflict FreshBooks raises on concurrent invoice creates. Both sides return HTTP 429 when throttled, so ml-connector backs off with jitter, refunds are processed one at a time per order, and every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A direct-to-consumer outdoor gear brand with roughly 40 staff sells through a BigCommerce storefront and keeps its books in FreshBooks. Before the integration, a bookkeeper exported the week's paid orders from BigCommerce and re-keyed each one into FreshBooks as an invoice, then logged the matching payment by hand and chased down which customer and product each line belonged to, which delayed the books and produced mismatched totals at month-end. With FreshBooks and BigCommerce connected, every paid BigCommerce order flows into FreshBooks as an invoice with the payment already recorded, the store customer mapped to a FreshBooks client, and each line tied to a FreshBooks item. The manual export-and-re-key step is gone and the revenue is booked the same day the order is paid.

What you can do

Create FreshBooks invoices from paid BigCommerce orders, with line items mapped to FreshBooks items.
Record the captured BigCommerce payment against the matching FreshBooks invoice automatically.
Keep FreshBooks clients aligned with BigCommerce customers as orders come in.
Bridge the BigCommerce X-Auth-Token key and the FreshBooks OAuth token, refreshing the FreshBooks token automatically.
Trigger on signed BigCommerce order webhooks, backfill by scheduled poll, and reuse the order number to avoid duplicate invoices.

Questions

Which direction does data move between FreshBooks and BigCommerce?: It runs mainly from BigCommerce into FreshBooks. Paid orders, their transactions, refunds, customers, and products move from BigCommerce and become FreshBooks invoices, recorded payments, clients, and items. The chart of accounts and tax mapping stay on the FreshBooks side, and BigCommerce never receives GL data because it has no accounting objects to hold it.
How does the integration avoid recording an order twice without an idempotency key?: Neither FreshBooks nor BigCommerce exposes an idempotency-key header. ml-connector reuses the BigCommerce order number as the FreshBooks invoice number, checks FreshBooks for that number before creating, and dedupes on a BullMQ jobId. Supplying the invoice number also sidesteps the 409 conflict FreshBooks raises when invoices are created concurrently without one.
Does the integration use BigCommerce webhooks or polling?: It uses both. Signed store/order webhooks trigger the sync as soon as an order is paid, and because the payload carries only a type and id, ml-connector fetches the full order and its transactions from the REST API before posting. A scheduled poll backfills missed events, which matters because BigCommerce auto-deactivates webhooks after long inactivity or sustained delivery failures.

Connect FreshBooks and BigCommerce

Free to use. Add your credentials, ping your real systems, and see if we fit.

Get started