Skip to main content

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.

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

RequirementVersion
Adobe Commerce (cloud)2.4.x
Adobe Commerce (on-prem)2.4.x
Magento Open Source2.4.x
PHP8.1, 8.2, or 8.3

​
Prerequisites

Before installing, ensure you have:
  1. A Numeral account at 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)
Run the following commands from your Magento root directory: 
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:
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: 
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:
FieldAction
Enable Numeral TaxSet to Yes
API KeyPaste the API key from your Numeral dashboard (Connections > Adobe Commerce)
Gateway URLLeave as default unless instructed by Numeral support
Test ModeSet to Yes for initial testing, No for production
Debug LoggingSet to Yes during setup to verify API communication, then disable
  1. Click Save Config
  2. 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

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

SettingDescriptionScope
Enable Numeral TaxEnables or disables the integration. When disabled, Magento’s native tax engine is used.Store View
API KeyYour Numeral connection API key. Found in the Numeral dashboard under Connections > Adobe Commerce. Stored encrypted in the database.Website
Gateway URLThe Numeral API endpoint. Do not change unless instructed by Numeral support.Default
Test ModeWhen enabled, calculations use the Numeral sandbox. No real tax transactions are recorded.Website
Debug LoggingLogs 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: 
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: 
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

ScenarioAPI calls per page load
Cart page (deferred calculation off)1
Cart page (deferred calculation on)0
Checkout shipping step1
Checkout payment step0 (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
ErrorCauseSolution
401 UnauthorizedInvalid or expired API keyGenerate a new key in the Numeral dashboard
500 Internal Server ErrorTransient API issueModule falls back to native tax automatically. Contact support if persistent
Connection timeoutNetwork issueCheck 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