Automated Ecommerce Reconciliation via A2X and Xero (n8n)

1. **Create Webhook in n8n**: Add a 'Webhook' node. Set the HTTP Method to POST. This URL will receive the payload from A2X's 'Post to Xero' event. 2. **Configure A2X Webhook Outbound**: In A2X, navigate to Settings > Integrations and paste your n8n Production Webhook URL to trigger on payout finalization. 3. **Set Up Xero Credentials**: In n8n, go to Credentials > Create New. Select 'Xero OAuth2 API'. Follow the OAuth flow to authorize n8n to access your Xero Organization. 4. **Data Normalization (Set Node)**: Add a 'Set' node to map A2X fields to Xero-friendly formats. Use expressions like `{{ $json["payout_date"].toDate() }}` to ensure date compatibility. 5. **Logic Gate (IF Node)**: Add an 'IF' node to check if `gross_sales` > 0. This prevents empty payouts from creating 'Zero-Dollar' invoices in Xero which cause sync errors. 6. **Create Xero Invoice**: Add a 'Xero' node. Action: 'Create' | Resource: 'Invoice'. Map the 'Line Items' using a 'Code' node if the payout contains multiple tax rates, or use the 'Fixed' mapping for simple summaries. 7. **Error Workflow**: Create a separate 'Error Trigger' workflow. Connect it to a Slack or Microsoft Teams node to notify your accounting team if a Xero API rate limit (50/min) is hit or if a chart-of-accounts mapping fails. 8. **Tracking Categories**: Use a second Xero node to 'Update' the created invoice, assigning 'Tracking Category' IDs (e.g., Region or Brand) received from the A2X metadata. 9. **Handling Concurrency**: In n8n Workflow Settings, set 'Execution Order' to 'FIFO' to ensure payouts are processed in chronological order to maintain ledger integrity.

| A2X Field | Xero Target Field | n8n Expression / Transformation | | :--- | :--- | :--- | | `payout_id` | `Reference` | `{{ $json.payout_id }}` (Required for reconciliation) | | `total_sales` | `Line Amount` | `{{ $json.total_sales.parseFloat() }}` | | `payout_date` | `Date` | `{{ $json.date.toISODate() }}` | | `tax_amount` | `TaxAmount` | Mapping required to Xero Tax Type code | | `account_code` | `AccountCode` | `{{ $json.mapping_code || '200' }}` (Default to Sales) | | `currency` | `CurrencyCode` | `{{ $json.currency.toUpperCase() }}` |

- **Xero Rate Limits**: Xero has a limit of 60 requests per minute. If processing a multi-year backlog, use the 'Split in Batches' node (batch size: 10) with a 'Wait' node of 5 seconds to avoid 429 Errors. - **Date String Mismatch**: A2X might send Unix timestamps or localized strings. Always use the n8n `DateTime` library to convert to ISO-8601 before sending to Xero. - **Duplicate Invoices**: Xero will error if an invoice with the same ID already exists. Use the 'Try' option on the Xero node or a 'Merge' node to check for existing invoices first. - **Self-Hosted Memory**: If self-hosting n8n on a small VPS, large A2X JSON payloads (500+ line items) can cause OOM (Out of Memory) errors. Increase `NODE_OPTIONS=--max-old-space-size=4096` if necessary.

- [ ] Execute Webhook node in 'Test' mode and send a sample payload from A2X. - [ ] Verify using the n8n 'Binary/JSON' toggle that all numerical values from A2X are parsed as Numbers, not Strings. - [ ] Check 'Execution' history to ensure the OAuth2 token for Xero refreshes automatically. - [ ] Log into Xero 'Draft Invoices' and confirm the 'Total' matches the A2X 'Net Payout' exactly. - [ ] Purge test data from Xero before switching the n8n Webhook to 'Production' URL.