Skip to main content

Using Numeral’s Tax Engine with Acumatica

This article walks you through installing the Numeral connector for Acumatica and ensuring accurate sales tax is applied.

Written by Sadie Rudiger
Updated yesterday

Numeral Acumatica Connector

The Numeral Connector for Acumatica automates sales tax calculation. When an AR Invoice, Sales Order, SO Invoice, or Credit Memo is created or updated, the connector sends the data to Numeral's tax engine, receives the calculated tax, and applies it directly to the Acumatica object — all without manual intervention. Acumatica automatically calls the plugin to calculate tax on save.

💡 Key capabilities:

  • Automatic tax calculation — Tax is calculated in real time on AR Invoices, Sales Orders, SO Invoices, and Credit Memos

  • Payment tracking — When a payment closes an invoice, Numeral is notified so the transaction is recorded

  • Product catalog sync — Inventory items are synced to Numeral for accurate tax classification

Prerequisites

Before installing the connector, ensure you have:

  • Acumatica ERP 2020 R2 or later

  • Administrator access to the Acumatica instance

  • A Numeral account with an API key (available in the Numeral dashboard)

Installation

⚠️ Important: Acumatica instance is restarted automatically after plugin installation, so plan for about 5 minutes downtime for the whole process

The connector is distributed as an Acumatica customization package (numeral-plugin-{version}.zip) and is installed through the Customization Projects screen.

Step 1: Import and Publish the Customization Package

  1. Log in to Acumatica as an administrator

  2. Navigate to Customization Projects (SM204505)

  3. Click Import and upload numeral-plugin-{version}.zip

  4. Select the NumeralConnector project and click Publish

  5. Wait for publishing to complete (Acumatica restarts automatically)

Step 2: Configure the Tax Plugin

  1. Navigate to Tax Plugins (TX102000)

  2. Enter NUMERAL as the Provider ID

  3. In the Plugin Type field, select: NumeralConnector.TaxProvider.NumeralTaxProvider, NumeralConnector

  4. Go to the Settings tab and configure:

    • API URL: Your Numeral API URL (default: https://acumatica-integration.numeralhq.com)

    • API Key: Your Numeral API authentication key

    • Sync Products on Test Connection: Enable to sync inventory items when testing connection

  5. Go to the Companies tab and add a row:

    • Select your Branch from the dropdown

    • Enter any value for Company Code (e.g. DEFAULT) — Numeral identifies clients by API key, not company code, but Acumatica requires this mapping

  6. Click Test Connection to verify credentials

  7. Click Save

Step 3: Create an External Tax Zone

  1. Navigate to Tax Zones (TX206000)

  2. Create a new tax zone (e.g. ID: NUMERAL)

  3. Check Is External Tax Provider

  4. Select Tax Plugin = NUMERAL

  5. Set a Tax Agency vendor (any active vendor marked as a tax agency)

  6. Set a Tax Payable Account (any active liability account)

  7. Click Save

Step 4: Assign the Tax Zone

Set the NUMERAL tax zone on your customers so it's used automatically on new documents:

  • Customer level: Customers (AR303000) > Shipping tab > Default Tax Zone

  • Branch level (global fallback): Branches (CS102000) > Default Tax Zone

Demo Videos: Connection Setup, Installation, Adding Invoices

Configuration Reference

Setup Screen Fields (NM101000)

Field

Description

Required

Default

API Key

Your Numeral API authentication key (stored encrypted)

Yes

-

API URL

The Numeral API endpoint

Yes

https://acumatica-integration.numeralhq.com

SYNCPRODUCTS

Sync Products on Test Connection

No

-

Usage Guide

Calculating Tax on a New Invoice

  1. Create a new AR Invoice (screen AR301000)

  2. Add line items with inventory items and quantities

  3. Save the invoice while it is in Hold status

  4. The connector will automatically calculate tax and apply it to the invoice

  5. You will see the NUMERAL Tax Zone applied and the tax total updated

Tracking a Paid Invoice

  1. Create and release an AR Invoice (the invoice must have been processed for tax)

  2. Create an AR Payment and apply it to the invoice

  3. Release the payment — once the payment reaches Closed status, the connector notifies Numeral

  4. The transaction ID is stored on the invoice for reference

Syncing Products

  1. Navigate to the Numeral Tax Plugin screen (NM101000)

  2. Click Sync Products

  3. All active inventory items are sent to Numeral

  4. A success message confirms the number of products synced

Troubleshooting

API calls failing

  • Use the Test Connection button to verify your credentials

  • Confirm the API URL is correct and reachable from the server

  • Check that the server firewall allows outbound HTTPS traffic

Tax not appearing on invoices

  • Verify the NUMERAL Tax Zone exists (screen TX206000)

  • Verify the NUMERAL Tax exists (screen TX205000)

  • Verify the NUMERAL Tax Category exists (screen TX205500)

  • Ensure at least one active GL Account exists (preferably a liability account) for the Tax Payable Account

Invoices not recalculating tax

  • Tax is only recalculated when the invoice balance changes

  • If the balance hasn't changed, the connector skips processing to avoid duplicate API calls

  • To force recalculation, modify a line item amount and save again

Uninstallation

To completely remove the Numeral Connector from your Acumatica installation:

Step 1: Unpublish and Delete the Customization Project

  1. Navigate to Customization Projects (SM204505)

  2. Select the NumeralConnector project

  3. Click Unpublish to remove the deployed files and site map entry

  4. Optionally delete the project from the list

Step 2: Run the Uninstall SQL Script

The customization project only manages files and site map entries. To remove the database objects created at runtime, run the uninstall SQL script:

  1. Open SQL Server Management Studio and connect to your Acumatica database

  2. Open Scripts/uninstall.sql

  3. Execute the script to remove:

    • NumeralSetup table

    • NUMERAL Tax and Tax Revision

    • NUMERAL Tax Zone and Tax Zone Detail

    • NUMERAL Tax Category and Tax Category Detail

    • Tracking columns from ARInvoice table (UsrNumeralTaxCalculationId, UsrNumeralTaxTransactionId, UsrNumeralProcessedAmount)

Step 3: Remove Access Rights

  1. Navigate to User Security > Access Rights by Screen (SM201020)

  2. Remove any access rights configured for NM101000

Step 4: Restart Acumatica

  1. Restart IIS or recycle the application pool

  2. Clear browser cache

💬 Questions? Reach out to our team anytime via the messaging widget in your Numeral dashboard.

Did this answer your question?