Automated HubSpot Deal to Xero Invoice Sync (n8n)

1. **Create HubSpot Credentials**: In n8n, go to Credentials > New. Search for 'HubSpot' and follow the OAuth2 steps to authorize your portal. 2. **Set up HubSpot Trigger**: Add a 'HubSpot Trigger' node. Set the 'Resource' to 'Deal' and 'Event' to 'Property Changed'. Choose `dealstage` as the property to watch. 3. **Filter for 'Closed Won'**: Add an 'IF' node. Set the condition to check if the new value of `dealstage` equals your portal's specific ID for 'Closed Won'. 4. **Fetch Line Items**: Use a 'HubSpot' node with the 'Get' action on the 'Deal' resource. Toggle 'Return All' and include 'Line Items' in the associated properties to get product data. 5. **Sync Contact to Xero**: Add a 'Xero' node. Use the 'Search' action on 'Contact'. Use an expression `{{ $json.company_name }}` to find a match. 6. **Create Contact Logic**: Add an 'IF' node to check if the search returned results. If empty, use another Xero node with the 'Create' action to sync the HubSpot Company/Contact details. 7. **Transform Line Items**: Add a 'Code' node or use expressions to map HubSpot Line Items to Xero's format. Note: Xero requires `Quantity` and `UnitAmount` to be numbers. 8. **Generate Invoice**: Add a 'Xero' node with 'Create' action on 'Invoice'. Set the 'Status' to 'DRAFT'. Map the Contact ID from step 5/6 and the array of line items from step 7. 9. **Update HubSpot Deal**: Add a final 'HubSpot' node to update the Deal. Map the Xero Invoice ID to a custom HubSpot property like `xero_invoice_link` for sales visibility. 10. **Error Handling**: Create a separate 'Error Trigger' workflow. Use an 'Error Trigger' node to catch failures and send a Slack notification or email to the admin.

| HubSpot Field (Source) | Xero Field (Destination) | n8n Expression / Transformation | | :--- | :--- | :--- | | `dealname` | `Reference` | `{{ $json.dealname }}` | | `associated_company` | `Contact` | `{{ $node["Xero-Search"].json.ContactID }}` | | `line_items[].name` | `LineItems[].Description` | Standard mapping | | `line_items[].price` | `LineItems[].UnitAmount` | `{{ parseFloat($json.price) }}` | | `line_items[].quantity`| `LineItems[].Quantity` | `{{ parseInt($json.quantity) }}` | | `closedate` | `Date` | `{{ $json.closedate }}` (Format: YYYY-MM-DD) | | (Static Value) | `Status` | `DRAFT` (Avoids unintended live billing) |

* **Rate Limiting**: HubSpot and Xero both enforce API limits. If processing bulk historical deals, use the 'Split in Batches' node in n8n to throttle requests. * **Schema Mismatches**: Xero expects a specific date format (ISO 8601). Use the n8n 'DateTime' node or `.toISOString()` in expressions if your HubSpot date format varies. * **Authentication Expiry**: n8n handles OAuth2 refresh tokens automatically, but if you self-host via Docker, ensure your instance has a persistent volume for the database so credentials aren't lost on restart. * **Currency Matching**: Ensure the HubSpot Deal currency code matches an active currency in Xero, or the API will return a 400 error.

- [ ] **Test Trigger**: Move a Deal to 'Closed Won' in HubSpot and verify n8n receives the webhook/polling event. - [ ] **Contact Search**: Verify the Xero node correctly identifies an existing contact by email or name to prevent duplicates. - [ ] **Line Item Precision**: Ensure the 'Code' or 'Set' node output for pricing uses two decimal places (n8n JSON preview is helpful here). - [ ] **Draft Creation**: Confirm a 'Draft' invoice appears in Xero with the correct Deal ID as the reference. - [ ] **Execution Log**: Check the n8n Execution History for any 'Node timeout' or '401 Unauthorized' errors.