How does the integration handle different product IDs between FreshBooks and ShipBob?

ml-connector attempts to match FreshBooks line items to ShipBob products first by UPC, then by SKU, then by exact product name. If no match is found after three attempts, the record is logged in the audit trail for manual review. You can configure custom product mapping rules per item to override the default matching behavior.

What happens if a FreshBooks invoice is updated or deleted after ShipBob receives the order?

If an invoice is updated, ml-connector checks for line item quantity changes and either adjusts the ShipBob order if it has not yet shipped, or logs a mismatch in the audit trail for manual resolution. If a FreshBooks invoice is deleted and ShipBob has already picked and packed the order, ml-connector does not delete the ShipBob order (since cancellation at that stage risks loss of goods). Instead, it logs the mismatch and notifies the customer account owner.

Do ShipBob return and damage events flow back into FreshBooks?

Yes. ShipBob return.created and return.updated events are logged in FreshBooks as fulfillment exceptions and attached to the original invoice. If a ShipBob warehouse reports damage during receiving, that event is also logged. ml-connector does not automatically adjust invoice amounts or create credit notes, since warehouse damage may or may not incur a cost depending on your vendor agreement.

FreshBooksShipBob

FreshBooks and ShipBob integration

FreshBooks manages your accounting and invoicing. ShipBob manages fulfillment and storage. Connecting them keeps your invoice records aligned with shipment reality: new invoices in FreshBooks can trigger fulfillment orders in ShipBob, and shipment events coming back from ShipBob update your invoice fulfillment status so your accounting reflects what has actually left the warehouse. ml-connector handles the different token lifetimes and headers each system requires.

How FreshBooks works

FreshBooks exposes invoices, clients, payments, expenses, and chart of accounts through REST APIs at https://api.freshbooks.com. Authentication uses OAuth2 Authorization Code grant (user-delegated, not client credentials), so the credential set belongs to one FreshBooks user account. Two distinct API namespaces serve accounting (/accounting/account/<accountId>) and time tracking (/timetracking/business/<businessId>). FreshBooks sends webhook events for invoice.create, invoice.update, payment.create, payment.update, and related finance events with HMAC-SHA256 signature verification. Webhook delivery ranges from seconds to several minutes and is not real-time. Invoice and payment status fields are read-only, computed by the system.

How ShipBob works

ShipBob exposes orders, shipments, products, inventory, and fulfillment centers through REST APIs at https://api.shipbob.com, with versioned path prefixes (/2026-01/). Authentication uses OAuth2 Authorization Code flow or Personal Access Token. Every API call requires an Authorization Bearer header and a shipbob_channel_id header identifying the application channel making the request. ShipBob sends webhook events for order.shipped, order.shipment.tracking.updated, return.created, and billing.charge.created with HMAC-SHA256 signature verification. Read operations span all merchant channels; write operations require the shipbob_channel_id header and only affect that specific channel.

What moves between them

The primary flow is FreshBooks to ShipBob: invoices and line items in FreshBooks are mapped to orders and order line items in ShipBob for fulfillment. Client names and contact information are mapped to ShipBob order metadata. ShipBob webhook events flow back into FreshBooks: order.shipped and order.shipment.delivered events update the invoice fulfillment status, and return or damage events are logged in FreshBooks for billing reference. The sync is event-driven from ShipBob and polling-based from FreshBooks for initial order creation.

How ml-connector handles it

FreshBooks tokens have no fixed expiry (they persist until revoked), so ml-connector caches the access token once issued and only refreshes on 401. ShipBob tokens expire in 1 hour, so ml-connector tracks the token issue time and proactively refreshes 5 minutes before expiry to avoid mid-request failures. Every ShipBob API call includes the required shipbob_channel_id header; ml-connector stores the channel ID per customer and validates it matches the credential set. FreshBooks invoice line items are mapped to ShipBob products and variants using UPC, SKU, or internal product ID as the matching key, with fallback to product name if direct ID is not available. ShipBob inventory units are in ounces and inches; ml-connector stores those weight and dimension conversions per variant to avoid unit mismatch. Webhook signatures are verified using HMAC-SHA256 on both platforms with different header names (FreshBooks uses X-FreshBooks-Hmac-SHA256; ShipBob uses webhook-signature). Failed webhook deliveries are retried by each platform and tracked in the audit log so they can be replayed manually if needed.

A real-world example

A small e-commerce business selling handmade goods issues invoices in FreshBooks for each order and ships via ShipBob fulfillment centers. Before the integration, the owner manually created orders in ShipBob from FreshBooks invoices and checked ShipBob daily to update invoice delivery status by hand. With FreshBooks and ShipBob connected, a new invoice in FreshBooks automatically generates a fulfillment order in ShipBob using the line item quantities and client address, ShipBob confirms receipt of goods and marks them in stock, and when ShipBob ships the order, the tracking and delivery status flows back into FreshBooks so the owner and customer see fulfillment progress without re-entry.

What you can do

Sync FreshBooks invoices and line items into ShipBob as orders and order line items, mapped by product SKU, UPC, or name.
Keep FreshBooks invoice fulfillment status in sync with ShipBob shipment events, including tracking updates and delivery confirmations.
Map FreshBooks client information to ShipBob order addresses and metadata so fulfillment centers have correct contact details.
Handle FreshBooks OAuth2 user-delegated tokens and ShipBob OAuth2 with automatic 1-hour token refresh and shipbob_channel_id header validation.
Track product weight and dimension unit conversions (ounces to pounds, inches to centimeters) so inventory is accurate across both systems.

Questions

How does the integration handle different product IDs between FreshBooks and ShipBob?: ml-connector attempts to match FreshBooks line items to ShipBob products first by UPC, then by SKU, then by exact product name. If no match is found after three attempts, the record is logged in the audit trail for manual review. You can configure custom product mapping rules per item to override the default matching behavior.
What happens if a FreshBooks invoice is updated or deleted after ShipBob receives the order?: If an invoice is updated, ml-connector checks for line item quantity changes and either adjusts the ShipBob order if it has not yet shipped, or logs a mismatch in the audit trail for manual resolution. If a FreshBooks invoice is deleted and ShipBob has already picked and packed the order, ml-connector does not delete the ShipBob order (since cancellation at that stage risks loss of goods). Instead, it logs the mismatch and notifies the customer account owner.
Do ShipBob return and damage events flow back into FreshBooks?: Yes. ShipBob return.created and return.updated events are logged in FreshBooks as fulfillment exceptions and attached to the original invoice. If a ShipBob warehouse reports damage during receiving, that event is also logged. ml-connector does not automatically adjust invoice amounts or create credit notes, since warehouse damage may or may not incur a cost depending on your vendor agreement.

Connect FreshBooks and ShipBob

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

Get started