Part 5: Advanced Tax Mapping Best Practice

This section details specific considerations for tax rate mapping, particularly when working with custom tax codes and multiple Xero organisations.

Advanced Tax Code Mapping Rules

The UniPhi-Xero integration works by referencing an underlying TaxType code (e.g., OUTPUT for GST On Income, or INPUT for GST on Expenses), rather than the user-facing tax rate name.

Tax Rate Type	Basis of Mapping	Rule for Integration
System-Defined Rates (e.g., GST on Income, GST on Expenses)	Mapped via TaxType code (OUTPUT/INPUT).	The codes are consistent across all Xero organisations, ensuring the mapping "consolidates" and works successfully for multi-entity setups.
Custom Rates (e.g., TAX001, Custom-VAT-15%)	Mapped via Name or Custom ID.	Warning: The system may struggle to identify or consolidate these custom IDs across multiple Xero organisations. If a custom tax rate is used in one organisation, the integration for a different organisation might report the mapping as None.

Best Practice for Multi-Entity Setups

To avoid mapping errors in multi-entity environments:

• Standardisation: Always standardise on the built-in/system-defined Xero tax rates (e.g., GST on Income, GST on Expenses) whenever possible, as their underlying TaxType codes are guaranteed to be consistent across all connected Xero organisations.

  
  

• Custom Code Isolation: If a custom tax rate must be used, ensure its unique identifier (name/code) is consistently and identically applied across every linked Xero organisation and accurately mapped in UniPhi to prevent the mapping defaulting to None.

→ Part 6: Orphaned Status