Testing & Scenarios

Table of Contents
  1. Introduction

    When testing an integration with TaxJar, we want to be confident that your platform correctly handles sales tax both ways:

    • Passing the correct data to the TaxJar API in each request
    • Returning the correct data from TaxJar using the API response

    In this guide, we’ll provide some high-level guidelines on how to test your integration effectively and a checklist of common testing scenarios.

    Sandbox Environment

    TaxJar provides a sandbox environment on all TaxJar Professional or higher plans for automated testing and development. You can generate a sandbox API token inside the TaxJar app under Account > TaxJar API. From there, you can point your API client to our sandbox URL at https://api.sandbox.taxjar.com.

    Integration Testing

    Your platform has a separate checkout calculation process to handle order details and return back totals. Typically, the TaxJar API extends or overrides your existing calculation process to provide sales tax. For this reason, the best way to test calculations involves integration testing:

    1. Create a mock order using details around a unique tax scenario.
    2. Ensure the TaxJar integration is enabled or included programmatically.
    3. Call your platform’s checkout calculation process with the TaxJar API to get the order totals with sales tax included.
    4. Capture the TaxJar API response as a fixture using your mocking or stubbing library and using it for ongoing tests (optional).
    5. Assert the order and line item totals equal their expected values.

    We recommend logging both the API request and response during this process so you can determine exactly what was passed to the TaxJar API and the resulting calculation.

    Verify a specific tax rate by using our sales tax calculator. Keep in mind that different rates may apply based on sourcing rules for individual states and where the merchant has nexus. If something doesn’t look right, send us the API request and response to review.

    For transactions, you’d follow a similar process for testing. Usually an integration will create a new transaction in TaxJar after an order is updated into a complete state. You would create a mock order, transition it to the complete state and ensure the order transaction was created in our API.

    Click Testing

    In addition to integration tests, you may want to outline a click testing process to run through each time you update your integration. For calculations, this would involve enabling the integration in your platform and testing customer-facing orders at checkout and merchant-facing backend orders directly in the browser.

    If the integration can be downloaded through a marketplace or directory, we recommend downloading the released version and installing it in a staging environment.

    Testing Scenarios

    We’ve provided a list of testing scenarios for both sales tax calculations and reporting. Use the request examples dropdown on the right of the API documentation for orders and addresses to test.

    Sales Tax Calculations

    Sales Tax Reporting

    Next: FAQs

    © 2024 TaxJar