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
Incorrect source-of-truth selection causes tax mismatches and reconciliation failures.
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
Incorrect model selection produces incorrect tax amounts and compliance risks.
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)
Q1. When should default taxes be used instead of imported taxes? A: Default taxes should be used when the client does not want XoroERP to calculate taxes and only requires placeholder tax values.
Q2. Why do tax mismatch errors occur for Shopify orders? A: Tax mismatch errors occur when XoroERP recalculates tax values and compares them with Shopify values.
Q3. Can Shopify taxes remain unchanged while Xoro calculates other orders? A: No. Once tax recalculation is enabled, the behavior applies globally.
Q4. Are Canadian taxes manually created in XoroERP? A: No. GST, PST, and HST are automatically configured in CAD instances.
Q5. When does PST apply on a sales order? A: PST applies only when the province is defined.
Q6. What happens if the province or state is not defined? A: GST is applied as the default fallback tax.
Q7. What does customer force tax do? A: It applies a predefined tax and ignores address-based calculation.
Q8. Can different items have different tax behavior in one order? A: Yes. Item-level force tax allows different tax treatment per item.
Q9. Which tax rule has the highest priority? A: Item-level force tax.
Q10. Does refunding amount only change the sales order quantity? A: No. It adjusts customer deposits only.
Q11. What happens if a refund is processed without restocking? A: Inventory is reduced.
Q12. Where can tax configuration be verified? A: In the Tax Assembly Center.
Q13. Can Avalara and Xoro tax systems operate together? A: Yes. Hybrid implementations are supported.
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 prevents tax mismatches, transaction failures, and inventory discrepancies.
Last updated
Was this helpful?