Adobe Commerce - Numeral API

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.

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:

A Numeral account at dashboard.numeralhq.com
An Adobe Commerce connection configured in the Numeral dashboard (Connections > Adobe Commerce)
An API key generated from the connection above
CLI access to your Magento installation (SSH or local terminal)

Installation via Composer (Recommended)

Composer Prerequisite: Configure Adobe Commerce Credentials

Composer must authenticate with repo.magento.com to download Adobe Commerce and Magento packages. Adobe Commerce uses a pair of credentials:

Public Key → Composer username
Private Key → Composer password

To download Adobe Commerce packages, the keys must belong to a MAGEID with access to the corresponding product or package. Get the credentials

Log in to the Adobe Commerce Marketplace
Open your account menu and select My Profile > Access Keys > Magento 2
Click Create A New Access Key
Assign a name that identifies where the key will be used, for example production-server
Copy both the Public Key and Private Key

Configure the credentials on the server The credentials must be configured for the same user that will run Composer during Magento deployments. Adobe recommends running installation commands as the application filesystem owner. Example running Composer as the Magento user (e.g. magento):

sudo -u magento -H composer config --global \
  http-basic.repo.magento.com \
  'YOUR_PUBLIC_KEY' \
  'YOUR_PRIVATE_KEY'

If you are already logged in directly as the user that runs Composer:

composer config --global \
  http-basic.repo.magento.com \
  'YOUR_PUBLIC_KEY' \
  'YOUR_PRIVATE_KEY'

Composer stores the credentials in the global auth.json file for the user that ran the command. The --global flag prevents the credentials from being stored inside the Magento project. You can check the location of Composer’s global directory (where auth.json lives) with:

sudo -u magento -H composer config --global home

Do not configure the credentials as root if Composer runs during deployments as a different user — each user has a separate global Composer directory and a separate auth.json. Never share or commit the Private Key to your repository.

Install the Module

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

Download the extension archive (numeral-module-tax-X.Y.Z-app-code.zip) from the Adobe Commerce Marketplace or GitHub Releases
Extract the archive into your Magento app/code/ directory. The resulting path should be app/code/Numeral/Tax/
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

Log in to the Magento Admin Panel
Navigate to Stores > Configuration > Numeral > Tax Settings
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

Click Save Config
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:

With Test Mode enabled, add a product to the cart in your storefront
Proceed to checkout and enter a US shipping address
At the shipping step, verify that tax amounts appear (calculated by Numeral)
Complete the order
In the Admin, navigate to Sales > Orders and open the test order
Click Invoice to create an invoice — this triggers a tax commit to Numeral
After invoicing, click Credit Memo to issue a refund — this triggers a tax void
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:

Go to Stores > Configuration > Numeral > Tax Settings
Set Test Mode to No
Set Debug Logging to No
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

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:

Cart line items, quantities, prices, discounts, and the shipping address are collected
A request is sent to the Numeral API Gateway (POST /order/calculate)
The API returns tax amounts per line item and for shipping
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.

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

Enable Test Mode in the module configuration
Place a test order through checkout
Verify tax amounts appear at the checkout shipping step
Create an invoice for the order
Create a credit memo for the order
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

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

Tax not appearing at checkout

Confirm the module is enabled: Stores > Configuration > Numeral > Tax Settings > Enable Numeral Tax = Yes
Verify the API Key is correct (check for leading/trailing spaces)
Enable Debug Logging and review var/log/numeral_tax.log for errors
Flush the cache: System > Cache Management > Flush Magento Cache

"0.00" tax amounts

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

API errors in logs

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

Module conflicts

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.

Cache issues

If configuration changes do not take effect:

Go to System > Cache Management
Click Flush Magento Cache
If using a full-page cache (Varnish, Fastly), purge that cache as well

Support

Dashboard: dashboard.numeralhq.com
Email: support@numeralhq.com

​Installation Guide

​System Requirements

​Prerequisites

​Installation via Composer (Recommended)

​Composer Prerequisite: Configure Adobe Commerce Credentials

​Install the Module

​Manual Installation

​Verify Installation

​Initial Configuration

​Validate the Installation

​Disable Test Mode for Production

​Uninstallation

​User Guide

​Configuration

​Settings Reference

​Scope Behavior

​How It Works

​Checkout Tax Calculation

​Invoice (Tax Commit)

​Credit Memo (Tax Void)

​Product Sync

​Fallback Behavior

​Testing Your Integration

​Using Test Mode

​Verification Checklist

​Reviewing Logs

​Performance Optimization

​Deferred Total Calculation

​In-Memory Cache

​Performance Impact

​Troubleshooting

​Support

Installation Guide

System Requirements

Prerequisites

Installation via Composer (Recommended)

Composer Prerequisite: Configure Adobe Commerce Credentials

Install the Module

Manual Installation

Verify Installation

Initial Configuration

Validate the Installation

Disable Test Mode for Production

Uninstallation

User Guide

Configuration

Settings Reference

Scope Behavior

How It Works

Checkout Tax Calculation

Invoice (Tax Commit)

Credit Memo (Tax Void)

Product Sync

Fallback Behavior

Testing Your Integration

Using Test Mode

Verification Checklist

Reviewing Logs

Performance Optimization

Deferred Total Calculation

In-Memory Cache

Performance Impact

Troubleshooting

Support