Automate Amazon Settlement Reconciliation to QuickBooks Online (n8n)

1. **Establish Credentials**: In n8n, go to 'Credentials' and create connections for 'Amazon Seller Central' (OAuth2) and 'QuickBooks Online' (OAuth2). Ensure you have 'Accounting' scopes enabled for QBO. 2. **Configure Amazon Trigger**: Add the 'Amazon Seller Central' node. Select the 'Order' resource and the 'On New Order' event. For settlements, choose 'On New Report' filtered by `GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE`. 3. **Handle Data Arrays with the Item Lists Node**: Amazon often returns orders in a list. Use the 'Item Lists' node to 'Split Out' items so each line item on an order is processed individually. 4. **Map Data via n8n Expressions**: Add a 'Set' node (now called 'Edit Fields') to transform Amazon's date format and currency strings into QBO-compatible numbers using expressions like `{{ $json.order_total.amount.toNumber() }}`. 5. **Deduplicate with Filter Node**: To prevent duplicate sales entries, use a 'QuickBooks Online' node to 'Get All' Sales Receipts filtered by `DocNumber` (Amazon Order ID). Follow this with an 'IF' node: if 'Check exists' is true, stop the workflow. 6. **Synchronize Customers**: Use the QBO node to 'Search' for a customer by email. If not found, use a 'Customer: Create' node. Reference the resulting `ID` for the next step. 7. **Create Sales Receipt**: Add the QBO node with the action 'Sales Receipt: Create'. Map the Customer ID from step 6 and line items from step 3. Crucially, map the Amazon Order ID to the 'Private Note' or 'DocNumber' for tracking. 8. **Process Fees via Journal Entry**: For settlements, Amazon reports fees as negative values. Use n8n logic to sum these and create a 'Journal Entry' in QBO, debiting your 'Amazon Fees' expense account and crediting 'Amazon Clearing Account'. 9. **Implement Error Handling**: Create a 'Error Trigger' workflow. When any node fails (e.g., QBO API rate limit), this node will catch the error and send a notification to Slack or Discord with the `executionId`. 10. **Enable Self-Hosting Perks**: If self-hosting n8n, ensure your `N8N_PAYLOAD_SIZE_MAX` environment variable is increased if you process large monthly settlement reports (5,000+ rows).

| Amazon Field | QuickBooks Field | n8n Expression / Strategy | Required? | | :--- | :--- | :--- | :--- | | `AmazonOrderId` | `DocNumber` | `{{ $json.AmazonOrderId }}` | Yes | | `BuyerEmail` | `Customer: Email` | `{{ $json.BuyerEmail || 'amazon_cust@noemail.com' }}` | Yes | | `ItemPrice` | `Line: Amount` | `{{ ($json.ItemPrice.Amount).toNumber() }}` | Yes | | `SKU` | `Line: ItemRef` | Search QBO Item by Name (SKU) | Yes | | `Commission` | `JournalEntry: Debit` | `{{ Math.abs($json.FeeAmount) }}` | Only for Settlements | | `PurchaseDate` | `TxnDate` | `{{ $json.PurchaseDate.split('T')[0] }}` | Yes |

* **SyncToken Conflict**: If updating an existing record, you must fetch the most recent `SyncToken` from QBO first. n8n will fail with a '400 Bad Request' if the token is stale. * **Rate Limiting**: QuickBooks Online has a limit of 40 requests per second. Use the 'Execute Workflow' node with a 'Wait' node if processing batch settlement reports to avoid hitting limits. * **Memory Management**: Processing 10,000+ settlement rows in a single execution can crash small n8n instances. Use the 'Split In Batches' node (batch size 500) to keep memory usage stable. * **Tax Codes**: QBO requires specific `TaxCodeRef` IDs. Do not map raw Amazon tax strings; use an 'IF' node or 'Switch' node in n8n to map Amazon's tax logic to your specific QBO Tax IDs.

- [ ] **OAuth Connection**: Both Amazon and QBO credentials show a green 'Connected' status. - [ ] **Dry Run**: Execute the 'Amazon Trigger' node manually to fetch real sample data into the n8n canvas. - [ ] **Expression Syntax**: Verify that currency amounts are displayed as numbers in the 'Output' panel, not as strings (no quotation marks). - [ ] **Duplicate Check**: Run the workflow twice for the same Order ID and confirm the 'IF' node successfully blocks the second attempt. - [ ] **Live Test**: Check the 'Execution Account' in QBO to ensure the 'Sales Receipt' appears with the correct line items and customer mapping.