• Developer Docs
• Integration Guides
• TaxJar

TaxJar

1. Installation & Setup
2. Returned & Cancelled Items
3. Updating Categories & Nexus Data
4. Add Nexus Regions
5. Product Categories
6. Customer Exemptions
7. SmartCalc Real Time Tax Calculations
8. Manual Order Actions
9. Historical Order Import
10. XML Provisioning
11. Updating the Module

Video Overview

TaxJar Sales Tax Automation Integration Guide from Miva on Vimeo.

Overview

TaxJar is a real-time sales tax calculation and state filing service which allows you calculate, display and collect taxes from your customers during checkout. It also allows you to optionally remit those taxes to each state via their Auto Filing Service.

TaxJar supports calculating taxes in the following countries: United States, Canada, Australia, and European Union.

Installation & Setup

To install the TaxJar module, first download it from the Miva App Store.

Next, upload it to your domain under Modules -> Add/Remove Modules.

Finally, to make it live you need to install it in your store. Under Store Settings -> Settings -> Sales Tax Calculation choose TaxJar and click Update.

Note: If you have a different Sales Tax Module installed, it will give you a warning message that switching Tax modules will remove all existing tax settings.

TaxJar Configuration

Once installed a new tab group will appear under Store Settings, towards the bottom. Here you have access to the following settings:

API Token - You must generate an API token in TaxJar to activate the service. This is done under Account -> SmartCalcs API. Here, you can click the Generate API Token button which will generate you a production and sandbox api token.

Here are instructions on how to generate you API token in TaxJar: https://support.taxjar.com/article/160-how-do-i-get-a-smartcalcs-sales-tax-api-token

API Endpoint - Drop down for Sandbox or Production Servers

Note: You will need to use the correct sandbox or production API token based on which API endpoint you are using in Miva. Using a sandbox API token with the production API endpoint will produce errors.

Automatically Create TaxJar Transactions- [recommended] With this setting enabled, when an order is placed by the customer Miva will make a call to TaxJar to push up the order data. This setting should be used if you are planning to use TaxJar for tax reporting and filing.

Nexus Regions - Three options are available for this setting:

1. Ignore Miva Merchant Configured Nexus Regions: With this setting Miva will ignore Nexus Regions listed in the Miva Merchant TaxJar Nexus tab and the TaxJar control panel. This setting will make a a tax API call during every checkout and transaction.
2. Calculate Using TaxJar Configured Nexus Regions: With this setting Miva will make a tax API call for only the Nexus Regions located in the Miva Merchant TaxJar Nexus tab batch list that are also in the TaxJar control panel.
3. Calculate Using Miva Merchant Configured Nexus Regions: With this setting Miva will make a tax API call for Nexus Regions from the Miva Merchant Tax Jar Nexus tab allowing the use of multiple international Nexus Regions. Important: This option must be selected if you wish to support multiple international locations. These locations are sent to TaxJar using the "nexus_addresses" parameter.

API Timeout: This is used in the event the TaxJar API is down or not responding. Miva will wait for 30 seconds and if no response is sent, it will fallback to teh Fallback Tax Rate. This alows for orders to still be created in Miva if the TaxJar API was down.

Fallback Tax Rate: In the event the TaxJar API is down, this fallback flat rate method for calculating tax is used. Default is 0 which will not charge taxes for the order but still allow the order to be placed.

Ship From: This allows you to specify a unique Ship From Address which will be used for Tax Calculations.

TaxJar Categories Last Updated: This shows you the last date and time the categories were updated from TaxJar.

Nexus Regions Last Updated: This shows you the last date and time the Nexus Regions were updated from TaxJar.

Nexus Regions - This is a list of each country and region for Nexus which is configured in TaxJar. If "Use Nexus Data to Limit API Calls" is checked, only countries and regions listed here will be taxed and have transactions pushed to TaxJar.

Order Number Format

When Miva pushes up a transaction to TaxJar we use a unique id for each transaction. Added in version 1.0002 the format used will contain the Miva order number so that it is searchable in taxjar.

<store_code>-<order:id>-<Random 32 Character String>

Returns & Cancelled Items

As of 1.0008, the TaxJar integration now supports TaxJar’s Returns API. This allows Miva to update TaxJar correctly to reduce your tax liability anytime an item is cancelled or returned in Miva.

There are three options in the configuration settings:

1. Return Received or Cancelled Items Triggers TaxJar Refund Update This option will automatically create a refund transaction in TaxJar for the item(s) marked as cancelled or when a RMA is created AND it is marked as received.
2. RMA Created or Cancelled Items Triggers TaxJar Refund Update This option will automatically create a refund transaction in TaxJar for the item(s) marked as cancelled or when a RMA is created.
3. Returned and Cancelled Items Are Not Submitted to TaxJar This option will not send items marked as returned or cancelled to TaxJar

Important Note: If either of the first 2 options are selected, the items will automatically be pushed to TaxJar as a refund. No action manual is needed other than creating the return or cancelling the items.

When you have an order with cancelled or returned items you never want to update the original transaction, since the refund transaction is doing that for you. Miva allows you to update the original transaction by clicking the Taxjar link and then clicking “Recalculate Taxes and Update TaxJar Order” This should only be done when there are no cancelled or returned items. Updating the original order after a refund transaction has been created will cause the Taxes to be under reported.

How to Update Product Categories & Nexus

If you add a new nexus location in TaxJar (say for example you have a new warehouse in a different state) you'll want to have Miva pull your new nexus location in to Miva. This can be done manually from Utilities -> Arrow Sub Menu -> Update TaxJar Categories/Nexus. This is also where you would pull in the latest Product Categories from TaxJar as they are constantly adding new categories.

Add Nexus Regions

To download the Nexus Regions from TaxJar select the 'Download Nexus Information' button from Store Settings -> TaxJar Nexus. This will download all Nexus Regions located in the TaxJar control panel.

Adding new Nexus Regions can be done by selecting the Add Nexus Regions button then entering the correct data for the region.

Note: When adding international regions that do not have region codes an asterisk ( * ) can be used in place of the region code to include the international country.

Product Categries

In order to get the most accurate tax rates, you’ll need to categorize each product you sell into one of TaxJar's fixed list of categories. The default category is to treat all products as fully taxable. However, every state has different tax rules for different products. TaxJar manages this for you as long as you correctly categorize your products.

To edit the product category, edit a product and from the main product details screen scroll down to the TaxJar tab group.

This TaxJar category assignment is also importable and exportable as a csustom field. Go to Data Management -> Import/Export -> Add/Update Products from CSV.

Below is a full list of TaxJar Catgories

Note: TaxJar is updating this list often. If you don’t see your products category check with TaxJar on timing for when it will be supported.

Updating Product Categories

Because TaxJar is constantly adding new product categories, you'll periodically want to update the categories in Miva. Under Edit Store -> TaxJar tab group It will show you the last time the categorie list was updated. To update this list, click the arrow next Utilities then "Update TaxJar Categories"

Customer Exemptions

TaxJar also has settings to mark individual customers as Tax Exempt. TaxJar supports 4 classifications:

• Non-Exempt (default)
• Wholesale
• Government
• Other

In addition, there is a customer level field to define state/country exemptions. This allows you to add state/country pairs in the following format (one per line):

<state>,<country>

Both of these settings are also importable and exportable via the standard customer import/export as custom fields. Under Data Management -> Export Customers to Flat File

Real Time Tax Calculations

One of the main features of TaxJar is to be able to display accurate sales tax amounts to your customers during checkout for any state your business have a physical presence (nexus). It allows you to collect the correct amount of sales tax from your customers. When the TaxJar module is assigned to your Miva store as the method to calculate sales taxes, Miva will automatically make a call to TaxJar when the customer is in the checkout process. The sales tax calculation process happens after the customer chooses a payment method and shipping method and continues on to the final screen to enter in their payment details (OPAY).

Setup In TaxJar

The SmartCalc tax calculations are enabled on a per state basis. To turn this on in TaxJar follow these steps:

• In TaxJar navigate to Account -> Business Profile -> State Nexus Settings
• Add the states which you have nexus
• Click Edit next to each state and ensure, the checkbox for SmartCalc APi is enabled

How Taxes are Calculated

Miva will take the cart contents and send them to TaxJar along with product TaxJar category. This product category is used to determine if the product is taxable in the state it is being sold. Also, if the customer is logged into their Miva customer account, the customer level exemption status will also be sent to TaxJar (non-exempt, wholesale, government, other). With all this data TaxJar will return a tax rate to the customer which gets added to the order.

Calculating Taxes in Admin

It's also possible to calculate (or recalculate) taxes for any order in the Miva admin. Sales taxes in admin are calculated in two scenarios:

1. Automatically any time an item is added, removed or updated on an order.
2. Manually by clicking the "Edit Shipping/Taxes/Charges" button and clicking the "Recalculate" button. This will update shipping but also recalculate all tax changes based on the current order.

Manual Order Actions

When viewing and updating an order within the Miva admin, there are 3 actions you can take to modify the order in TaxJar.

Insert Order To TaxJar

All orders placed manually via the Miva admin will need the order manually pushed to TaxJar if you wish to use TaxJar for reporting (and filing). This allows the transaction to be recorded in TaxJar. To insert the order into TaxJar click the TaxJar Link on the order detail screen:

Update Order In TaxJar

If an order changes after it was placed, such as an item was added, the tax amount is likely to change as well. To ensure TaxJar has the most up to date tax information, it's important to also push the order changes to TaxJar as well. Just recalculating taxes on the order does not automatically push the updated tax amount to TaxJar for filing and reporting.

To push the order and tax changes to TaxJar, click the TaxJar link and click Update TaxJar Order

Delete Order in TaxJar

If an order is cancelled, returned or refunded in Miva you’ll want to ensure that the order and the taxes on the order get removed from TaxJar so that reporting and state filing data in TaxJar is accurate. To delete an order from TaxJar click the TaxJar link on the order detail screen and select Delete TaxJar Order

With all these actions, if you have ""Limit Nexus Data to Limit API Calls"" set, these calls to insert, update or delete will only be made if the order state matches a nexus state.

Historical Import

If you plan on using TaxJar for state filing then it is strongly recommended you import the current calendar years historical orders so that TaxJar has all the data you need to file for each state. TaxJar has a CSV import format to allow you to import your historical orders. Please reference this article for instructions on how to import the CSV into TaxJar: https://support.taxjar.com/article/173-import-edit-transactions-with-a-csv

Batch Report

We’ve provided a template batch report you can add to your Miva store which will easily allow you to select a range of orders and export to the correct CSV format TaxJar is expecting.

A couple things to note about the export:

1. It only exports orders which are not Cancelled, Backordered, RMA Issued or Refunded.
2. It does not do anything related to refunds. ie if you refunded an order but never changed the status or tax amount its possible the tax value could be incorrect.
3. TaxJar Recommends to keep file size at 10,000 orders or less. If you have more than 10k orders to import it should be split up into multiple files.

Setup Instructions

1. Under Utilities ->Template Based Batch Report Add a new Order Batch Report.

2. For the template copy and paste in the code below:
3. Assign the "http_headers" item to the page with the following settings:
   • Content-Type text/csv
   • Content-Disposition attachment; filename="axjar_order_export.csv"
   
4. Finally to generate the CSV go to Order Processing, filter the orders to the date range you want, use CTRL + a to select all orders and click Batch Actions -> Batch Report


When you click Run Report a Blank popup window will open and a csv file will appear to download. If you are processing thousands of orders here, the file make take a few minutes before it is ready to download.

If you are attempting to export thousands of orders, it may be required to split up the orders into chunks to avoid report timeout issues.

XML Provisioning

The following XML Provisioning functions are available to use:

These xml functions can be used via the JSON API using: https://docs.miva.com/json-api/functions/provision_store

Updating The Module

Periodically we will release updates to the TaxJar module to fix bugs and add new features. Here are the steps to update the module.

1. Download the new module from the app store https://apps.miva.com/taxjar-sales-tax-automation.html
2. In the Miva admin go to Modules -> Search for "TaxJar"
   
3. Select the record and click the edit icon
4. Change to the "Files" tab and click upload
   
5. In the popup, check the "Overwrite" box, and browse your computer for the new file and click upload
   
6. Once the popup closes, click Update in Miva to save.