> ## Documentation Index > Fetch the complete documentation index at: https://docs.numeral.com/llms.txt > Use this file to discover all available pages before exploring further. # Adobe Commerce > Real-time US sales tax calculation for Adobe Commerce and Magento Open Source. Numeral Tax replaces Magento's native tax engine with Numeral's real-time tax calculation service. When a customer reaches checkout, the module sends the cart contents and shipping address to the Numeral API, which returns precise tax amounts. Tax is automatically committed when an invoice is created and reversed when a credit memo is issued. If the Numeral API is unavailable, Magento's native tax engine is used as an automatic fallback. Numeral Tax in Magento *** ## Installation Guide ### System Requirements | Requirement | Version | | ------------------------ | ---------------- | | Adobe Commerce (cloud) | 2.4.x | | Adobe Commerce (on-prem) | 2.4.x | | Magento Open Source | 2.4.x | | PHP | 8.1, 8.2, or 8.3 | ### Prerequisites Before installing, ensure you have: 1. A **Numeral account** at [app.numeralhq.com](https://app.numeralhq.com) 2. An **Adobe Commerce connection** configured in the Numeral dashboard (Connections > Adobe Commerce) 3. An **API key** generated from the connection above 4. **CLI access** to your Magento installation (SSH or local terminal) ### Installation via Composer (Recommended) Run the following commands from your Magento root directory: ```bash theme={null} composer require numeral/module-tax bin/magento module:enable Numeral_Tax bin/magento setup:upgrade bin/magento setup:di:compile bin/magento cache:clean ``` ### Manual Installation 1. Download the extension archive (`numeral-module-tax-X.Y.Z-app-code.zip`) from the Adobe Commerce Marketplace or GitHub Releases 2. Extract the archive into your Magento `app/code/` directory. The resulting path should be `app/code/Numeral/Tax/` 3. Run the following commands from the Magento root: ```bash theme={null} bin/magento module:enable Numeral_Tax bin/magento setup:upgrade bin/magento setup:di:compile bin/magento cache:clean ``` ### Verify Installation Confirm the module is active: ```bash theme={null} bin/magento module:status Numeral_Tax ``` Expected output: `Module is enabled` ### Initial Configuration 1. Log in to the **Magento Admin Panel** 2. Navigate to **Stores > Configuration > Numeral > Tax Settings** 3. Under **General Settings**, configure the following fields: | Field | Action | | ---------------------- | ---------------------------------------------------------------------------- | | **Enable Numeral Tax** | Set to **Yes** | | **API Key** | Paste the API key from your Numeral dashboard (Connections > Adobe Commerce) | | **Gateway URL** | Leave as default unless instructed by Numeral support | | **Test Mode** | Set to **Yes** for initial testing, **No** for production | | **Debug Logging** | Set to **Yes** during setup to verify API communication, then disable | 4. Click **Save Config** 5. Go to **System > Cache Management** and click **Flush Magento Cache** ### Validate the Installation After configuration, perform a test order to confirm the integration is working: 1. With **Test Mode** enabled, add a product to the cart in your storefront 2. Proceed to checkout and enter a US shipping address 3. At the shipping step, verify that tax amounts appear (calculated by Numeral) 4. Complete the order 5. In the Admin, navigate to **Sales > Orders** and open the test order 6. Click **Invoice** to create an invoice — this triggers a tax commit to Numeral 7. After invoicing, click **Credit Memo** to issue a refund — this triggers a tax void 8. Check the Numeral dashboard to confirm the calculation, commit, and void were recorded If **Debug Logging** is enabled, review `var/log/numeral_tax.log` for API request and response details. ### Disable Test Mode for Production Once validation is complete: 1. Go to **Stores > Configuration > Numeral > Tax Settings** 2. Set **Test Mode** to **No** 3. Set **Debug Logging** to **No** 4. Click **Save Config** and flush the cache Tax calculations will now be recorded as live transactions in Numeral. ### Uninstallation ```bash theme={null} bin/magento module:disable Numeral_Tax bin/magento setup:upgrade composer remove numeral/module-tax bin/magento setup:di:compile bin/magento cache:clean ``` The `numeral_calculation_id` column added to the `sales_order` table will remain in the database but has no effect when the module is disabled. *** ## User Guide ### Configuration Navigate to **Stores > Configuration > Numeral > Tax Settings** in the Magento Admin. #### Settings Reference | Setting | Description | Scope | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | **Enable Numeral Tax** | Enables or disables the integration. When disabled, Magento's native tax engine is used. | Store View | | **API Key** | Your Numeral connection API key. Found in the Numeral dashboard under Connections > Adobe Commerce. Stored encrypted in the database. | Website | | **Gateway URL** | The Numeral API endpoint. Do not change unless instructed by Numeral support. | Default | | **Test Mode** | When enabled, calculations use the Numeral sandbox. No real tax transactions are recorded. | Website | | **Debug Logging** | Logs API requests and responses to `var/log/numeral_tax.log`. Enable only during troubleshooting. | Default | #### Scope Behavior * **Store View** settings can be configured per store view, allowing different stores to enable or disable Numeral Tax independently. * **Website** settings apply to all store views under a website. The API key and test mode are shared across store views within the same website. * **Default** settings apply globally across the entire Magento installation. ### How It Works #### Checkout Tax Calculation When a customer enters their shipping address at checkout, the module intercepts Magento's tax calculation: 1. Cart line items, quantities, prices, discounts, and the shipping address are collected 2. A request is sent to the Numeral API Gateway (`POST /order/calculate`) 3. The API returns tax amounts per line item and for shipping 4. Tax amounts are mapped back into Magento's tax display at checkout The module caches identical requests within a single page load, so Magento's multiple internal `calculateTax()` calls result in only one API call per unique cart state. #### Invoice (Tax Commit) When an invoice is created for an order, the module sends a commit request to the Numeral API. This finalizes the tax transaction and creates the fiscal record. This happens automatically — no manual action is required beyond creating the invoice through the normal Magento workflow. Creating an Invoice #### Credit Memo (Tax Void) When a credit memo is created, the module sends a void request to reverse the tax transaction for the refunded amount. Both full and partial credit memos are supported. #### Product Sync When a product is saved in the Magento Admin, the module sends the product data to Numeral so that product categorization and tax rules can be applied correctly. #### Fallback Behavior If the Numeral API is unavailable (network error, timeout, server error), the module automatically falls back to Magento's native tax engine. The order proceeds normally with native tax amounts. No manual intervention is needed. When fallback occurs, no tax transaction is recorded in Numeral. The order's `numeral_calculation_id` field remains empty, and subsequent invoice/credit memo events are skipped for that order. ### Testing Your Integration #### Using Test Mode 1. Enable **Test Mode** in the module configuration 2. Place a test order through checkout 3. Verify tax amounts appear at the checkout shipping step 4. Create an invoice for the order 5. Create a credit memo for the order 6. Check the Numeral dashboard to confirm the test transactions #### Verification Checklist * [ ] Tax amounts display correctly at checkout * [ ] Order total includes the calculated tax * [ ] Invoice creation succeeds and commits the tax transaction * [ ] Full credit memo reverses the tax transaction * [ ] Partial credit memo sends the correct refund amount * [ ] Disabling the module reverts to Magento's native tax calculation * [ ] API failure falls back to Magento's native tax engine gracefully #### Reviewing Logs Enable **Debug Logging** and check `var/log/numeral_tax.log` for API request/response details: ```bash theme={null} tail -f var/log/numeral_tax.log ``` Each log entry includes the request payload, response body, HTTP status code, and response time. ### Performance Optimization #### Deferred Total Calculation For US-focused stores where showing tax only at checkout is standard, enable Magento's deferred total calculation to skip tax estimation on the cart page: ```bash theme={null} bin/magento setup:config:set --deferred-total-calculating 1 bin/magento cache:clean ``` This eliminates all API calls from the cart page. Tax is calculated only when the customer enters their shipping address at checkout. #### In-Memory Cache The module includes an in-memory payload-hash cache that deduplicates the 4–8 calls Magento makes to `calculateTax()` per page load. Identical payloads within the same HTTP request reuse the cached response. No additional caching configuration is needed. #### Performance Impact | Scenario | API calls per page load | | ------------------------------------ | ----------------------- | | Cart page (deferred calculation off) | 1 | | Cart page (deferred calculation on) | 0 | | Checkout shipping step | 1 | | Checkout payment step | 0 (cached) | ### Troubleshooting 1. Confirm the module is enabled: **Stores > Configuration > Numeral > Tax Settings > Enable Numeral Tax = Yes** 2. Verify the **API Key** is correct (check for leading/trailing spaces) 3. Enable **Debug Logging** and review `var/log/numeral_tax.log` for errors 4. Flush the cache: **System > Cache Management > Flush Magento Cache** * Verify the shipping address is in a taxable jurisdiction * Check that products have the correct tax class assigned in Magento * Review the Numeral dashboard for the calculation details — the API may have returned zero tax legitimately | Error | Cause | Solution | | --------------------------- | -------------------------- | ---------------------------------------------------------------------------- | | `401 Unauthorized` | Invalid or expired API key | Generate a new key in the Numeral dashboard | | `500 Internal Server Error` | Transient API issue | Module falls back to native tax automatically. Contact support if persistent | | `Connection timeout` | Network issue | Check server connectivity to the Gateway URL | If another tax extension is installed (Avalara, TaxJar, Vertex), disable it before enabling Numeral Tax. Only one tax calculation provider should be active at a time. If configuration changes do not take effect: 1. Go to **System > Cache Management** 2. Click **Flush Magento Cache** 3. If using a full-page cache (Varnish, Fastly), purge that cache as well *** ## Support * **Dashboard:** [app.numeralhq.com](https://app.numeralhq.com) * **Email:** [support@numeralhq.com](mailto:support@numeralhq.com)