Shopify–XoroERP Tax Configuration, Calculation & Refund Behavior
1. Overview
This document provides a consolidated reference for tax configuration, tax calculation behavior, Canadian tax logic, force tax rules, tax synchronization, and refund processing between XoroERP and Shopify.
2. Functional Workflow
2.1 Tax Strategy Definition (Source of Truth Selection)
Step 1: Determine Tax Calculation Ownership
Before configuration begins, the client must define where taxes are calculated:
Shopify
XoroERP
Third-party tax engine (e.g., Avalara)
This decision determines all downstream system behavior.
Step 2: Define Product and Order Tax Flow
Based on the selected ownership:
System calculates tax
System imports tax
System stores tax as placeholder only
2.2 Default Tax vs Imported Tax Setup
Default Tax Configuration (Placeholder Model)
Used when Xoro does not calculate taxes.
For US implementations, one default tax item per state is typically created.
Process:
Create default tax items with 0% rate
Assign tax items by state or region
Use tax only as reference value
Imported Tax Database (Calculation Model)
Used when Xoro calculates taxes.
Imported taxes increase system complexity and processing load.
Process:
Import detailed tax database
Enable automatic tax calculation
Maintain jurisdiction-level tax structures
2.3 Tax Calculation Model Selection
Xoro supports three calculation models:
Origin-Based: tax calculated from seller location
Destination-Based: tax calculated from shipping address
Origin-Hybrid: jurisdiction-specific combination
2.4 Address-Based Tax Calculation Behavior
Address accuracy is mandatory for correct tax calculation.
When address-based calculation is enabled:
System reads shipping or billing address
Postal code and state/province determine tax applicability
System calculates tax using jurisdiction rules
2.5 Shopify vs Xoro Tax Calculation Behavior
When Shopify Calculates Taxes
Xoro imports tax values
No recalculation should occur
When Xoro Recalculates Taxes
System calculates tax from configuration
Compares with Shopify values
Mismatch triggers validation errors
Partial override of Shopify tax values is not supported.
2.6 Tax Mismatch Handling
When mismatch occurs:
System detects rate differences
Fallback tax mapping is applied
Tax percentages may be aggregated
Transaction posts using default tax configuration
Resolution requires configuration validation or tax database updates.
2.7 Canadian Tax Configuration (CAD Instances)
Instance Setup
CAD instances automatically provision GST, PST, and HST
Tax assemblies are created during instance setup
Manual tax creation is not required
Tax Availability Validation
Taxes are available only in CAD environments
Tax Assembly Center displays configured tax structures
2.8 Canadian Tax Operation Logic (GST, PST, HST)
PST applies only when the province is defined
GST is applied when province is missing
Tax Operation State controls PST applicability
Incorrect state configuration prevents PST calculation.
2.9 Customer-Level Force Tax Application
Customer must be marked taxable
Customer force tax applies predefined tax
Address-based logic is ignored
Applies to API, uploads, and manual orders
2.10 Item-Level Force Tax Application
Applies tax at item level
Supports mixed-tax orders
Overrides customer tax and address logic
2.11 Force Tax Priority Hierarchy
Tax application follows strict priority:
Item-level force tax
Customer-level force tax
Address-based tax calculation
Higher priority rules override lower-level logic.
2.12 Multi-Entity & Cross-Border Tax Behavior
Some implementations support:
Multiple companies in one instance
Multiple country tax structures
System behavior:
Taxes configured per legal entity
Entity registration determines tax applicability
Cross-border transactions increase accounting complexity
2.13 Third-Party Tax Engine Integration (Avalara)
When enabled:
Avalara provides real-time tax rates
Xoro records transaction values
Hybrid implementation is supported across regions
Avalara overrides native tax logic
2.14 Auto Tax Creation for International Orders
For non-US and non-Canada orders:
System creates tax records automatically
Prevents order failures from missing tax configuration
Uses state or country-level structure
2.15 Refund Processing Workflow (Shopify → XoroERP)
Supported Refund Types
Full refund
Partial refund
Quantity refund
Amount-only refund
Refund behavior depends on restocking selection.
2.16 Restocking vs Non-Restocking Behavior
Restock + Quantity Refund
Sales order quantity updated
Inventory returned to stock
Amount-Only Refund
Customer deposit refunded
Sales order quantity unchanged
No Restock
Inventory adjustment occurs
On-hand quantity decreases
Incorrect refund selection causes inventory inconsistencies.
3. Transaction-Level Behavior
3.1 Order Import from Shopify
Reads tax values
Recalculates if configured
Validates tax amounts
Posts or raises mismatch error
3.2 Sales Order Tax Calculation
Reads address
Applies GST/PST/HST or jurisdiction tax
Applies force tax if enabled
3.3 Refund Processing
Updates sales order
Adjusts deposits or inventory
Records credit memo entries
4. Core Configuration Logic
Tax source-of-truth controls system behavior
Default tax items required for fallback scenarios
Tax overrides operate independently
Entity registration determines tax applicability
Address accuracy required for calculation
Tax Assembly Center must be validated
5. Structured Examples
Shopify Tax Recalculation Conflict Shopify calculates tax but Xoro recalculates → mismatch error.
CAD Address-Based Tax Province defined → PST + GST applied.
Customer Force Tax Fixed GST applied regardless of address.
Mixed-Tax Order Item force tax overrides customer tax.
Refund Without Restock Inventory reduced and deposit adjusted.
6. Important Rules & Constraints
Tax source of truth must be defined before configuration
Default tax items required for fallback handling
Canadian taxes auto-configured in CAD instances
PST requires province configuration
Item force tax overrides all other logic
Refund type directly impacts inventory
Multi-country setup increases accounting complexity
7. Best Practices
Confirm tax ownership during onboarding
Validate entity registration before setup
Verify address accuracy before testing
Validate tax assemblies during implementation
Use force tax only for controlled scenarios
Align refund behavior with warehouse operations
Never modify tax configuration without validation
8. Common Mistakes & Pitfalls
Situation / Mistake
Result / System Impact
Changing tax settings without confirming tax source of truth or client requirements
Incorrect tax calculation, reconciliation issues, and potential compliance risk
Importing tax database without creating default tax fallback items
Persistent tax mismatch errors and transaction validation failures
Enabling tax recalculation when Shopify is the source of truth
Order sync failures due to tax amount mismatch
Selecting incorrect tax calculation model (Origin, Destination, Hybrid)
Incorrect tax amounts and regulatory non-compliance
Ignoring legal entity registration during tax setup
Incorrect tax collection across jurisdictions
Incorrect or incomplete customer address (missing province/postal code)
Incorrect address-based tax calculation
Incorrect Tax Operation State configuration in CAD instances
PST not applied correctly or incorrect tax results
Incorrect refund type or restocking selection
Inventory inconsistencies and incorrect financial records
Processing refunds without validating warehouse restocking behavior
On-hand inventory mismatch and reconciliation issues
Ignoring multi-entity tax structure during setup
Complex accounting reconciliation and incorrect tax application
9. Frequently Asked Questions (FAQs) -Taxes & Refund Behavior
When should default taxes be used instead of imported Shopify taxes?
Default taxes should be used when the business does not want XoroERP to calculate taxes and only needs placeholder tax values for Shopify orders.
This is typically useful when:
Tax calculations are fully managed in Shopify
XoroERP is used only for recording transactions
What users should do:
Enable default taxes if tax calculation is not required in XoroERP
Ensure reporting expectations are aligned, as tax values will not be recalculated
Why do tax mismatch errors occur for Shopify orders?
Tax mismatch errors occur when XoroERP recalculates taxes and compares them with the values received from Shopify.
If there is any difference between:
Shopify-calculated tax
XoroERP-calculated tax
the system flags it as a mismatch.
What users should do:
Decide whether Shopify or XoroERP should be the source of truth for tax
Disable recalculation if Shopify taxes need to remain unchanged
Ensure tax configurations match across both systems
Can Shopify taxes remain unchanged while XoroERP calculates taxes for other orders?
No, this is not supported.
Once tax recalculation is enabled in XoroERP, it applies to all orders globally, including Shopify orders.
What users should do:
Choose a single tax handling approach:
Either rely on Shopify taxes
Or allow XoroERP to recalculate taxes for all orders
Are Canadian taxes manually created in XoroERP?
No, Canadian taxes such as GST, PST, and HST are automatically configured in CAD-based XoroERP instances.
What users should do:
Review pre-configured tax rules
Ensure province/state information is correctly captured for accurate tax application
When does PST apply on a sales order?
PST is applied only when the province is specified in the customer or order address.
What users should do:
Ensure province/state fields are populated in customer and order details
Verify address accuracy during order import
What happens if the province or state is not defined?
If the province or state is missing, XoroERP applies GST as the default fallback tax.
What users should do:
Always provide complete address details
Validate customer records to avoid incorrect tax application
What does “Customer Force Tax” do?
Customer Force Tax overrides normal tax calculation and applies a predefined tax rule, regardless of the customer’s address.
What users should do:
Use this setting when a fixed tax treatment is required
Apply carefully, as it ignores location-based tax rules
Can different items have different tax behavior within the same order?
Yes, this is supported through Item-Level Force Tax.
This allows:
Different tax rules to be applied to different items within the same order
What users should do:
Configure item-level tax rules where required
Use this for mixed tax scenarios (e.g., taxable vs non-taxable items)
Which tax rule has the highest priority in XoroERP?
Item-Level Force Tax has the highest priority.
If applied, it overrides:
Customer-level tax rules
Address-based tax calculations
What users should do:
Review item-level tax settings when unexpected tax values appear
Ensure correct configuration at item level
Does refunding amount only affect sales order quantity?
No, refunding an amount does not change the sales order quantity.
Instead:
It adjusts the customer deposit or financial balance
What users should do:
Review the financial impact in deposits or credit memos
Do not expect quantity changes for amount-only refunds
What happens if a refund is processed without restocking?
If restocking is disabled during a refund:
Inventory is reduced and not returned to available stock
This is typically used when items are:
Damaged
Not resellable
What users should do:
Enable restocking for the resellable items
Disable only when the inventory should not return to stock
Where can tax configuration be verified in XoroERP?
Tax configuration can be reviewed in the:
Tax Assembly Center
What users should do:
Verify tax rules and mappings
Check configurations if mismatches or errors occur
Can Avalara and XoroERP tax systems be used together?
Yes, both systems can operate together in a hybrid setup.
This allows:
External tax calculation (Avalara)
Internal tax handling (XoroERP)
What users should do:
Configure integration settings correctly
Clearly define which system handles which transactions
Key Takeaway
Tax behavior depends on configuration choices made in XoroERP
Consistency between Shopify and XoroERP is critical
Proper setup ensures accurate tax calculation and reporting
10. Conclusion
Accurate tax configuration and refund handling ensure stable financial reconciliation, correct inventory tracking, and regulatory compliance between Shopify and XoroERP. Establishing a clear tax source of truth, validating regional tax rules, configuring force tax priority correctly, and aligning refund behavior with operational workflows prevent tax mismatches, transaction failures, and inventory discrepancies.
Last updated
Was this helpful?