Automated A2X to QuickBooks Online Financial Reconciliation (n8n)

1. **Create Webhook Node**: Start your n8n workflow with a Webhook node (Method: POST). Copy the Production URL and paste it into the A2X 'Custom Export' or Notification settings. 2. **Configure Credentials**: In n8n, go to 'Credentials' and add 'QuickBooks Online OAuth2'. Ensure you select the 'Accounting' scope during the authorization prompt. 3. **Set Data Structure (Edit Fields)**: Use an 'Edit Fields' (formerly Set) node to map the A2X JSON array. Use n8n expressions like `{{ $json.body.settlement_id }}` to normalize the payout reference. 4. **Handle Multi-Line Items (Split Out)**: Use a 'Split Out' node if the A2X payload contains multiple lines (e.g., Sales, Fees, Shipping). This allows n8n to iterate through each line for the Journal Entry mapping. 5. **Aggregate for QBO**: After transforming line items, use the 'Aggregate' node to combine them back into a single array formatted specifically for the QuickBooks `Line` property. 6. **Execute Journal Entry**: Add the 'QuickBooks Online' node. Select the 'Journal Entry' resource and 'Create' action. Map the `Line` property to your aggregated array and the `DocNumber` to the A2X Settlement ID. 7. **Implement Duplicate Prevention**: Before the QBO node, add a 'QuickBooks Online' node with the 'Search' action. Search for a Journal Entry where `DocNumber` equals your Settlement ID. Use an 'If' node to stop the workflow if a match is found. 8. **Setup Catch-All Error Workflow**: Create a separate workflow with an 'Error Trigger' node. Link your main workflow to this error handler in the 'Settings' tab to catch API timeouts or mapping errors. 9. **Self-Hosting Optimization**: If self-hosting n8n, ensure your `N8N_PAYLOAD_SIZE_MAX` environment variable is increased, as A2X settlement files with many SKUs can exceed the default 16MB limit.

| A2X Field | QBO Field | Transformation / Expression | | :--- | :--- | :--- | | `settlement_id` | `DocNumber` | `{{ $json.settlement_id.toString() }}` (Required) | | `payout_date` | `TxnDate` | `{{ DateTime.fromISO($json.date).toFormat('yyyy-MM-dd') }}` | | `lines[].amount` | `Line.Amount` | `{{ Math.abs($json.amount) }}` (QBO requires positive values) | | `lines[].type` | `Line.DetailType` | Fixed value: `JournalEntryLineDetail` | | `lines[].account` | `AccountRef` | `{{ $json.account_id }}` (Use n8n Lookup Table if IDs differ) | | `currency` | `CurrencyRef` | `{{ $json.currency_code || 'USD' }}` |

• **Rate Limiting**: QuickBooks Online API has a limit of 40 requests per second. If processing batch historical data, use the n8n 'Wait' node or 'Split in Batches' (set to 10-20 items) to avoid 429 errors. • **Balanced Entries**: QBO will reject a Journal Entry if Total Debits do not equal Total Credits. Always use a 'Code' node or 'Sum' expression to validate balance before the QBO node. • **Large Payloads**: A2X settlements can be massive. For n8n instances with low RAM, use the 'Split in Batches' node to process line items in chunks of 50. • **Account Mapping**: Ensure the Account IDs in the A2X payload match the 'Internal ID' in QBO, not just the name. Use a 'Lookup' node in n8n to map names to IDs if necessary.

- [ ] **Test Webhook**: Trigger a test export from A2X and verify the JSON appears in n8n 'Listen' mode. - [ ] **Validate Mapping**: Ensure the `Amount` field in the QBO node is a number type, not a string. - [ ] **Check Sandbox**: Always run the first execution against a QuickBooks Sandbox company before Production. - [ ] **Verify Idempotency**: Run the same A2X payload twice to ensure the 'Duplicate Prevention' logic correctly blocks the second attempt. - [ ] **Confirm Balancing**: Verify in n8n execution logs that the sum of Credits and Debits sent to QBO equals zero.