> For the complete documentation index, see [llms.txt](https://docs.xorosoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xorosoft.com/xoroerp-1/utilities/manage-tax-services-avalara-integration/workflow-with-added-tax-services.md). # Workflow with Added Tax Services *** ### **Validate Workflow** Once Avalara is integrated into Xoro, it will be shown under the “Active Services”.

* Available actions: * Edit * Disable * Delete

After configuration, tax calculation must be validated through transactions. *** ### **Pre-Configuration Requirements** *** #### **Customer Setup (Entity Use Code)** **Path:**\ Customer → Sales Tax Tab **Field:**\ Entity Use Code

*** **What this means** This field indicates whether a customer qualifies for a **tax exemption**. If your customer falls under a special category—such as Federal Government, State Government, or Charitable Organization—you can assign an appropriate Entity Use Code. This helps the system apply the correct tax treatment automatically. *** **How it works** * If an Entity Use Code is defined:\ The system checks the exemption rules and applies reduced or zero tax where applicable * If not defined:\ The customer is treated as a regular taxable customer, and full tax is applied *** #### **Item Setup (Tax Category Code)** **Path:**\ Item → Tax Settings Tab **Field:**\ Tax Category Code

*** **What this means** This field defines **how a product or service should be taxed**. Each item can belong to a specific tax category (for example: general goods, food, digital services, etc.), and different categories may be taxed differently depending on the location. *** **How it works** * If a Tax Category Code is assigned:\ The system uses it to apply the correct tax rules for that item * If not assigned:\ The system may not be able to determine the correct tax, which can result in incorrect or inconsistent tax calculations *** ### **Transaction Flow** When Avalara is configured in the **Manage Tax Services** module, tax calculation in XoroERP becomes automated and is seamlessly integrated into the transaction workflow. *** #### **How Tax is Calculated** While creating a transaction (such as a Sales Order), the system gathers key details like: * Customer information (including Entity Use Code, if defined) * Item details (including Tax Category Code) * Shipping and billing address When you click **Save**, XoroERP sends this information to **Avalara**, which evaluates the applicable tax based on location, product type, and customer tax status. The calculated tax is then displayed in the **Tax Summary pop-up**, where you can review the tax breakdown before applying it. *** #### **Tax Calculation Process** * The transaction flow demonstrated here is based on the **Sales Order module** * The corresponding transactions recorded in Avalara are shown in the screenshots below for reference

1. **Add Customer** and create transaction (Sales Order / Invoice / Purchase Order) * System validates: * Customer setup * Item tax code * Address details 2. **Add Item** to the Sales Order 3. Click **Save**. This will open a pop-up window where you can view and calculate tax.

* Transaction details are sent to Avalara * Avalara evaluates: * Address * Item taxability * Customer exemption * Tax is returned * XoroERP applies the tax

*** #### **How Tax is Recorded** After reviewing the tax in the pop-up, you click **Apply & Save** to finalize the transaction. For Sales transactions, the tax is **not immediately recorded in Avalara at the Sales Order stage**. The transaction is recorded only after the Sales Order is converted to **converted into an Invoice**, as that is considered the final document for tax reporting. * If **Record Document** is enabled:\ The transaction is recorded in **Avalara** at the Invoice stage, and is used for tax reporting and filing * If **Record Document** is disabled:\ The tax is calculated and applied in XoroERP, but the transaction is not recorded in Avalara *** #### **In simple terms:** * Sales Order → Tax is calculated and shown * Invoice → Tax is finalized, and the transactions are recorded as shown below. (if enabled)

* If **Record Document** is disabled:\ The tax is applied within XoroERP, but the transaction is not saved in Avalara. *** ### **Modules Affected** * Sales Order * Invoice * Purchase Order *** ### **Special Scenarios** *** #### **Customer Tax Exemption** * Controlled via Entity Use Code * Tax reduced or removed if applicable

*** #### **Returns and Adjustments** * Triggered via Invoice Credit Memo * Tax recalculated proportionally, and transactions are recorded successfully in Avalara.

***

*** #### **Void Transactions** * Cancels tax record in Avalara * Prevents incorrect reporting *** #### **Multi-Region Tax Handling** * Avalara determines tax based on jurisdiction *** #### **Common Scenarios** | Scenario | Cause | Result | | ------------------- | ------------------- | ----------------------- | | Invalid Address | Incorrect data | Tax not calculated | | Missing Tax Code | Configuration issue | Incorrect or failed tax | | Avalara Disabled | Toggle off | No tax calculation | | Avalara Unavailable | External issue | Retry or failure | *** #### **System Behavior** * Displays error messages * Logs failure details * Allows correction and retry *** ### **FAQs** *** **Q1: Why is the tax not calculated?**\ Check: * Avalara configuration * Tax code setup * Customer configuration * Address details *** **Q2: Why is tax zero?** * The Customer may be exempt **Q3: Can Avalara be disabled without removing the configuration?** * Yes, using the enable/disable toggle *** **Q4: What happens if Record Document is disabled?** * Tax is calculated but not stored in Avalara *** ### **System Behavior Summary** * Valid configuration → Tax calculated * Missing tax code → Warning or incorrect tax * Invalid address → Tax calculation fails * Exempt customer → Reduced or zero tax *** ### **Final Understanding** * XoroERP sends transaction data * Avalara calculates tax * XoroERP applies the result * Optional recording ensures compliance --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.xorosoft.com/xoroerp-1/utilities/manage-tax-services-avalara-integration/workflow-with-added-tax-services.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.