FreshBooks and Amazon Seller Central integration

What moves between them

The flow runs from Amazon Seller Central into FreshBooks. ml-connector reads Amazon orders and creates a FreshBooks invoice for each one, with line items priced from the order, and matches or creates a FreshBooks client for the buyer where buyer detail is available. After Amazon releases a settlement, ml-connector reads the settlement report and the Finances transactions, then posts the captured proceeds as FreshBooks payments and the selling, fulfillment, and referral fees as FreshBooks expenses against the chart of accounts, with refunds booked the same way. Amazon SKUs are aligned to FreshBooks items so each sale lands on a consistent ledger line. FreshBooks is the system of record for accounting, so ml-connector does not write invoices or payouts back into Amazon. Reads run on a schedule, typically hourly for orders and per settlement cycle for finances.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the Amazon side it holds the Login with Amazon refresh token, mints a fresh one-hour access token before expiry, caches it, and passes the marketplace_id and region on every call since Amazon does not infer them. On the FreshBooks side it completes the OAuth authorization-code grant, refreshes the rotating FreshBooks refresh token on each use, and resolves the accountId and businessId from the /me endpoint up front. Because Amazon delivers events only through EventBridge or SQS rather than plain HTTP, the connector polls Orders, Finances, and the settlement Reports on a schedule and follows Amazon NextToken cursors rather than page numbers. Settlement is asynchronous, so payouts and fees post only after Amazon releases the settlement report, which the connector creates, polls until done, and downloads from the presigned S3 URL. New invoices are created against a supplied invoice_number so a retry does not produce a duplicate, and they are advanced from Draft to Sent so they appear in FreshBooks reports. Amazon SKUs are mapped to FreshBooks items and Amazon fee types to FreshBooks expense categories before any posting. Both APIs return HTTP 429 under load, so the connector backs off and retries with jitter, and every record carries a full audit trail and can be replayed if a FreshBooks write fails. FreshBooks PII deletes use the vis_state soft-delete pattern rather than HTTP DELETE.

A real-world example

A small consumer-goods seller with about fifteen staff sells through its own Amazon storefront and keeps its books in FreshBooks. Before the integration, the bookkeeper downloaded the Amazon settlement report every two weeks and hand-entered the gross sales, then split out referral and fulfillment fees and refunds line by line, which meant the Amazon payout in the bank rarely tied cleanly to revenue until well into month-end. With FreshBooks and Amazon Seller Central connected, each order posts as a FreshBooks invoice as it settles, and every payout cycle books the proceeds, fees, and refunds against the right accounts automatically. The bank deposit already reconciles to recorded sales and fees, and the manual settlement-report re-keying is gone.

What you can do

• •Create a FreshBooks invoice with line items for each settled Amazon Seller Central order.
• •Post Amazon disbursements as FreshBooks payments and selling, fulfillment, and referral fees as FreshBooks expenses.
• •Book Amazon refunds into FreshBooks against the correct accounts so payouts reconcile to recorded sales.
• •Bridge the Login with Amazon refresh-token flow and the FreshBooks two-ID account login, refreshing tokens automatically.
• •Poll Amazon Orders, Finances, and settlement Reports on a schedule, with retries and a full audit trail on every record.

Questions

Which direction does data move between FreshBooks and Amazon Seller Central?

Data moves from Amazon Seller Central into FreshBooks. Orders become FreshBooks invoices, and settlement proceeds, fees, and refunds become FreshBooks payments and expenses. FreshBooks is the accounting system of record, so ml-connector does not write invoices or payout data back into Amazon.

Does the integration rely on webhooks for real-time updates?

No. Amazon Seller Central has no plain HTTP webhook; it delivers push events only through AWS EventBridge or SQS, and FreshBooks webhook latency is not guaranteed. ml-connector polls the Amazon Orders, Finances, and Reports APIs on a schedule and follows Amazon NextToken cursors to pull new and changed records reliably.

How are Amazon fees and payouts recorded in FreshBooks?

After Amazon releases a settlement, ml-connector reads the settlement report and Finances transactions, then posts the captured proceeds as FreshBooks payments and the referral, fulfillment, and other selling fees as FreshBooks expenses against the chart of accounts. Settlement is asynchronous, so these post only once Amazon makes the settlement report available, which keeps the FreshBooks ledger aligned with the actual bank deposit.