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.

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. Acumatica automatically calls the plugin to calculate tax on save. Key capabilities:
  • Automatic tax calculation 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

  • 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

​
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, enter: NumeralConnector.TaxProvider.NumeralTaxProvider, NumeralConnector
  4. Go to the Settings tab and configure:
    • API URL: https://acumatica-integration.numeralhq.com
    • API Key: Your Numeral API key from the dashboard
    • Sync Products on Test Connection: Enable to sync inventory items when testing the 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. Set Tax Plugin to 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

​
Configuration Reference

The setup screen (NM101000) exposes the following fields:
FieldDescriptionRequiredDefault
API KeyYour Numeral API authentication key (stored encrypted)Yes—
API URLThe Numeral API endpointYeshttps://acumatica-integration.numeralhq.com
Sync Products on Test ConnectionSync inventory items when testing connectionNo—

​
Export Historical Invoices to CSV

On the Tax Plugins screen, an Export Historical Invoices to CSV action button appears in the row toolbar when the Numeral plugin is selected. Clicking it generates a downloadable .csv file containing all released AR invoices (both direct AR invoices and invoices originating from Sales Orders), formatted to Numeral’s Standard Manual Line Upload format. When to use: Run this once during initial setup to back-fill Numeral with your transaction history before going live with real-time tax calculation.

​
Non-Taxable Line Item Exclusion

The connector handles documents that contain a mix of taxable and non-taxable line items — for example, taxable goods alongside non-taxable packaging or services. Line items with a blank or EXEMPT Tax Category ID are excluded from the Numeral API request and automatically assigned $0 tax. Tax is calculated only against eligible line items, and any rounding remainder is absorbed by the last taxable line. No configuration is needed — this behavior is automatic.

​
Troubleshooting

Use the Test Connection button to verify your credentials. Confirm the API URL is correct and reachable from the server, and that the server firewall allows outbound HTTPS traffic.
Verify the following all exist:
  • NUMERAL Tax Zone (TX206000)
  • NUMERAL Tax (TX205000)
  • NUMERAL Tax Category (TX205500)
Also ensure at least one active GL Account (preferably a liability account) is set as the Tax Payable Account.
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.
Confirm you’re on Acumatica 2020 R2 or later. Older builds do not include the tax plugin extensibility points the project depends on.

​
Uninstallation

  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