# 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 {% hint style="info" %} Incorrect source-of-truth selection causes tax mismatches and reconciliation failures. {% endhint %} *** #### 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 {% hint style="info" %} Incorrect model selection produces incorrect tax amounts and compliance risks. {% endhint %} *** #### 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.xorosoft.com/xoroerp-1/connected-apps/xoro-shopify-implementation-deep-dive/shopify-xoroerp-tax-configuration-calculation-and-refund-behavior.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.