Skip to main content

​
Introduction

The Numeral API is designed to ensure accurate and compliant sales tax calculation, collection, and filing. To achieve the smoothest possible implementation and avoid pitfalls that may impact compliance, it is essential to follow the recommended practices outlined in this guide.

​
1. Review Documentation Thoroughly

A successful launch begins with a thorough review of the Numeral API Documentation. Correct configuration and data formatting are critical:
  • Address Fields
    • Province: The state, province, or region of the transaction. Must be a valid 2-digit ISO 3166-2 subdivision code.
      • US address example:
        • Valid address: “CO” (Colorado)
        • Invalid address: “California”
      • Non-US address example:
        • Valid address: “ON” (Ontario)
        • Invalid address: “British Columbia”
    • Country: Must be a valid ISO 3166-1 alpha-2 country code.
      • Examples:
        • United States: “US”
        • Canada: “CA”
        • Australia: “AU”
    • Postal Code, Province, and Country: Required fields.
    • Address Lines and City: Can be empty strings if needed. Precise rates may not be possible, but Numeral will still return high-quality estimated rates.
  • Amounts
    • All amounts must be submitted in cents for USD (or the lowest denomination for all currencies). For example, $100.25 USD should be passed in as 10025.
Attention to these details ensures accurate calculations and prevents errors in downstream filings.

​
2. Test in a Production-Like Environment

Typically, we recommend using a **test API key in a production-like environment for at least two weeks** before switching to a production key. Risks of skipping this step include:
  • Orders without proper tax applied
  • Misaligned product and product category mappings
  • Incomplete transaction or refund workflows, leading to inaccurate filings
Thorough testing ensures confidence and stability when moving into production.

​
3. Verify Registrations and Rate Availability

With a test API key, rates are always returned for development purposes. However, when using a production API key, rates are returned only:
  • In jurisdictions where you are registered
  • When using the 2025 API version with automatic_tax=auto
Before going live, confirm that your registrations are active and that you receive rates in the expected jurisdictions. Active registrations are those listed under the “Processing” and “Registered” tabs here.

​
4. Emergency Fallback Rate

While Numeral maintains 99.99% uptime, unforeseen outages may occur. To safeguard compliance:
  1. On API 500 or 504 responses, retry once or twice to account for transient network issues.
  2. If the issue persists, default to an 8% fallback tax rate for all orders until you see responses from the Numeral API again.
  3. Manually upload that data as a csv to the Numeral dashboard so that we have that sales data from that outage window.
Again, although this is unlikely to occur it is best practice to be safe and prepared in case of emergency so that tax doesn’t have to paid out of pocket. This approach ensures tax continues to be collected, protecting compliance and revenue integrity.

​
5. Product Categorization

Tax rates vary by product type. Assigning the closest possible Numeral tax category to each product ensures rates are as accurate as possible. Poor categorization may result in over- or under-collection. Here is a complete list of Numeral’s product categories.
For clients using product categories in calculation requests, follow this workflow:
  1. Product Mapping
    • Implement internal logic to map products or line items to the appropriate Numeral product category.
      • Generally speaking, we recommend creating products and using reference_product_ids in calculation if you have a lot of SKUs, and we recommend using product_category in calculation requests if you primarily are only selling a couple of different product categories. The choice is entirely up to you on how you want to use the API. Typically we see SaaS customers prefer to use product categories and ecom companies prefer using product ids.
  2. Checkout Flow
    • Collect customer address and line items.
    • Call the Calculations API.
    • Apply the returned tax rates to the checkout.
    • Record the calculation_id from the response.
  3. Transaction Recording
    • On order completion, call the Transactions API with the calculation_id.
    • This records the sale for filings and returns a transaction_id.
  4. Refunds
    • Store the transaction_id for each transaction.
    • Use this ID when processing refunds to ensure accurate adjustments.
For a diagram of this please see the docs here: https://docs.numeralhq.com/objects/calculations

​
7. Capturing all sales

To ensure Numeral can file accurately for your business, you’ll need to confirm that your API implementation captures all intended sales. For instance, if you sell products via a checkout flow on your website and via manual invoices, you should be apply a tax rate and send sales data to Numeral in both scenarios.

​
8. Error Handling

The Numeral API throws many different types of errors depending on the requests that are sent. Here are some general errors that the API throws as well as error handling advice: Authentication Errors:
  • invalid_api_key - API key format invalid or not found
  • revoked_api_key - API key has been deactivated
Validation Errors:
  • missing_field - Required field not provided
  • incorrect_type - Field has wrong data type
  • invalid_country_code - Unsupported country code
  • invalid_currency_code - Unsupported currency code
  • unrecognized_field - Unknown field in request
  • negative_number_required - Field must be negative (refunds)
Business Logic Errors:
  • calculation_not_found - Invalid calculation_id reference
  • calculation_expired - Calculation older than 24 hours
  • transaction_not_found - Invalid transaction_id reference
  • transaction_already_exists - Duplicate transaction creation
  • product_not_found - Invalid product reference
  • customer_not_found - Invalid customer reference
  • invalid_tax_code - Invalid product tax code
  • missing_origin_address - Origin address required for transaction
Resource Conflicts:
  • duplicate_product - Product with same ID already exists
  • duplicate_customer - Customer with same ID already exists
Recommended Error Handling Strategy
  1. Immediate Retry (500/503): Retry once for server errors
  2. Rate Limiting (429): Implement exponential backoff
  3. Validation Errors (400): Log and fix request format
  4. Auth Errors (401): Check API key validity
  5. Fallback: Apply 8% emergency rate for persistent 500/503 errors

​
Conclusion

By following these practices—thoroughly reviewing the documentation, testing in production-like environments, verifying registrations, preparing fallback logic, accurately categorizing products, and adhering to the recommended workflow—you will ensure smooth, compliant, and resilient tax collection and remittance with the Numeral API.