Skip to content

TaxJar#

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. Once downloaded upload it to your Miva store under: Settings -> Domain Settings -> Modules and select the Add Module button. Finally, assign the module to your store. Go to Settings -> Modules find the module and click install.

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 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. 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.

Create Transaction When Order Is Shipped or Created
This setting was added in Miva 10.01.00. To maintain backwards compatibility any customer who upgrades will have this setting set to “Created” However, for new installs this value will be set to “Shipped”. This means that no order will be pushed to TaxJar until the order gets marked as shipped in Miva. This allows you to make order modification without having to constantly re-sync data to TaxJar.
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.

Note

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 allows 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>

Item Level Tax#

Miva 10.01.00 introduces item level sales tax. All taxes are now calculated and stored at the line item level, in addition to the order level taxes. TaxJar now supports item level sales tax. This is the default way (and only way) taxes are now calculated snd stored. In addition to item level taxes, the integration also supports taxes on shipping and other custom charges such has handling.

Post Order Modifications#

Miva’s TaxJar integration has been updated in Miva 10.01.00 to completely automate all actions such as returns and other post order modifications which had to be done manually in previous versions. The settings to manually push an order to TaxJar or to Update an order in TaxJar have been removed. Also, all settings around returned and cancelled items have also been removed. These settings have been replaced with the following logic for when an order is pushed to TaxJar or Refunded from TaxJar.

  • Ability to manual push or update an order to TaxJar has been removed. This now happens automatically
  • A New Setting has been added to control when the order is pushed to TaxJar. The default for new installs of Taxjar is “Shipped” which waits until the order is marked as shipped in Miva before pushing to TaxJar. For partial shipments, once any shipment in the order is marked as shipped, the entire transaction is pushed to TaxJar. To maintain backwards compatibility any customer who upgrades will have this setting set to “Created” which is how the integration functions pre-10.01.00.
  • Anytime the Tax on an order changes in Miva, we now make a call to TaxJar to compare the order record they have vs what we have stored in Miva. If these are not the same, Miva refunds the entire previous transaction and will create a brand-newtransaction with the current order/tax in Miva.
  • The Miva order details screen for TaxJar now displays the current details of the order saved in TaxJar so it’s easy to verify tax details in Miva matches what is in TaxJar.
  • Transactions are now processed via a Queue, setup as a Scheduled Task. Transactions are put into this queue and batched together to reduce the total number of API calls and allow for additional logging if required.The default delay is 5 minuteswhichcan be adjusted as needed.

There are 2 statuses when viewing the transaction details:

  • Queued - This means that the order has been put into the TaxJar queue and will by pushed to TaxJar as soon as the trigger delay elapses, which is a 5 minute default
  • Current - This means that the tax and order information is in sync with both TaxJar and Miva.

If no order has been pushed TaxJar the following message will be displayed

TaxJar Order Queue#

As of 10.01.00 TaxJar transactions are put into a queue before they are pushed to TaxJar. This queue gets processed every 5 minutes, which can be adjusted under the modules settings. The queue provides the following benefits:

  • It provides a window in time over which modifications to a TaxJar order will be batched together, to reduce the total number of TaxJar transactions
  • Through logging to the scheduled task logic, it provides an audit trail (if desired) tracking changes to TaxJar orders
  • It provides a fallback mechanism for the synchronous order creation should the Taxjar API be down
  • By using the scheduled task trigger mechanism, there is some control over the delay between TaxJar order API calls. Additionally, by clearing the trigger on the scheduled task, merchants could choose to update their TaxJar orders only on some regular schedule (perhaps outside of normal business hours)

The Miva Orders batch list provides a order custom field to see which orders are currently in the Queue to be pushed to TaxKar.

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 Settings -> 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 Settings -> 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 Categories#

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 custom field. Go to Data Management -> Import/Export -> Add/Update Products from CSV.

Below is a full list of TaxJar Catagories

Service Category Code Countries Description
Installation Services 10040 US Installation services separately stated from sales of tangible personal property.
General Services 19000 US Miscellaneous services which are not subject to a service-specific tax levy. This category will only treat services as taxable if the jurisdiction taxes services generally.
Advertising Services 19001 US Services rendered for advertising which do not include the exchange of tangible personal property.
Parking Services 19002 US Service of providing usage of a parking space.
Admission Services 19003 US Admission charges associated with entry to an event.
Training Services 19004 US Services provided to educate users on the proper use of a product.
Professional Services 19005 US Professional services which are not subject to a service-specific tax levy.
Dry Cleaning Services 19006 US Services provided in the cleaning of clothing and/or fabrics.
Repair Services 19007 US Services provided to restore tangible personal property to working order or optimal functionality.
Hairdressing Services 19008 US Services provided to cut and style human hair.
Printing Services 19009 US Services provided to apply graphics and/or text to paper or other substrates which do not involve an exchange of tangible personal property.
Clothing 20010 US All human wearing apparel suitable for general use.
Clothing - Swimwear 20041 US Bathing suits and swim suits.
Software as a Service 30070 US Pre-written software, delivered electronically, but access remotely.
Digital Goods 31000 US, EU Digital products transferred electronically, meaning obtained by the purchaser by means other than tangible storage media.
Candy 40010 US Candy and similar items
Supplements 40020 US Non-food dietary supplements.
Food & Groceries 40030 US, EU, AUS Food for humans consumption, unprepared
Soft Drinks 40050 US Soft drinks, soda, and other similar beverages. Does not include fruit juices and water.
Bottled Water 40060 US Bottled, drinkable water for human consumption.
Prepared Foods 41000 US Foods intended for on-site consumption. Ex. Restaurant meals.
Non-Prescription 51010 US, EU Drugs for human use without a prescription.
Prescription 51020 US, EU Drugs for human use with a prescription.
Books 51020 US, EU Drugs for human use with a prescription.
Textbooks 81110 US Religious books and manuals, printed.
Religious Books 81120 US Textbooks, printed.
Magazines & Subscriptions 81300 US Periodicals, printed, sold by subscription.
Magazine 81310 US, EU Periodicals, printed, sold individually.
~~Other Exempt~~ ~~99999~~ ~~All~~ ~~Item is exempt. Important Note: Other Exempt is currently not supported in AutoFile~~

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.

Important:

The “Other Exempt” or 99999 category no longer exists in TaxJar, so it has been removed from the Miva admin. Now, order charges can have configurable tax codes, similar to AvaTax. In addition, the following changes to the existing logic have been made, where the 99999 code was being used.

  • A non-taxable product, with a tax code configured, it is sent (this is the current functionality).
  • A non-taxable product, without a tax code configured, is not sent.
  • A taxable product, without a tax code configured, is sent with a blank tax code (this is the current functionality).
  • Non-taxable charge, with a tax code configured, is sent.
  • Non-taxable charge, without a tax code configured, is not sent.
  • Taxable charge, without a tax code configured, is sent with a blank tax code (this is the current functionality).

The following provisioning tags must be added for this functionality.

<ChargeTaxCode_Add>
   <Type>xxx</Type>
   <TaxCode>yyy</TaxCode>
</ChargeTaxCode_Add>

<ChargeTaxCode_Update type="xxx" taxcode="yyy" />

<ChargeTaxCode_Delete type="xxx" />

Updating Product Categories#

Because TaxJar is constantly adding new product categories, you’ll periodically want to update the categories in Miva. Under Settings -> Store Settings -> TaxJar tab group It will show you the last time the categories 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#

Miva’s TaxJar integration has been updated in Miva 10.01.00 to completely automate all actions such as returns and other post order modifications which had to be done manually in previous versions. The settings to manually push an order to TaxJar or to Update an order in TaxJar have been removed. Also, all settings around returned and cancelled items have also been removed. Please see this section for details on how updates to orders are handled.

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.

For the template copy and paste in the code below:

<mvt:assign name="g.delimiter" value="','" />
<mvt:assign name="g.newline" value="asciichar(10)" />

provider&mvt:global:delimiter;order_id&mvt:global:delimiter;transaction_type&mvt:global:delimiter;completed_at&mvt:global:delimiter;customer_name&mvt:global:delimiter;shiptocity&mvt:global:delimiter;shiptostate&mvt:global:delimiter;shiptozip&mvt:global:delimiter;shiptostreet&mvt:global:delimiter;shiptocountrycode&mvt:global:delimiter;shipping_amount&mvt:global:delimiter;handling_amount&mvt:global:delimiter;discount_amount&mvt:global:delimiter;total_sale&mvt:global:delimiter;sales_tax&mvt:global:delimiter;from_country&mvt:global:delimiter;from_state&mvt:global:delimiter;from_city&mvt:global:delimiter;from_zip&mvt:global:delimiter;from_street&mvte:global:newline;

<mvt:foreach iterator="order" array="admin_order:orders">

<mvt:comment>Only send orders which are not: 300 = Cancelled, 400 = Backordered, 500 = RMA Issued, 600 = Returned </mvt:comment>
<mvt:if expr="l.settings:order:status NE 300 OR
          l.settings:order:status NE 400 OR
          l.settings:order:status NE 500 OR
          l.settings:order:status NE 600">

<mvt:comment>Reset Charges Variables</mvt:comment>
<mvt:assign name="l.settings:shipping_charge"   value="'0.00'" />
<mvt:assign name="l.settings:tax_charge"    value="'0.00'" />
<mvt:assign name="l.settings:handling_charge"   value="'0.00'" />
<mvt:assign name="l.settings:discount_amount"   value="'0.00'" />

<mvt:foreach iterator="charge" array="order:charges">
    <mvt:if expr="l.settings:charge:type EQ 'SHIPPING'">
        <mvt:assign name="l.settings:shipping_charge" value="l.settings:charge:disp_amt" />
    </mvt:if>

    <mvt:if expr="l.settings:charge:type EQ 'TAX'">
        <mvt:assign name="l.settings:tax_charge" value="l.settings:charge:disp_amt" />
    </mvt:if>

    <mvt:if expr="l.settings:charge:type EQ 'HANDLING'">
        <mvt:assign name="l.settings:handling_charge" value="l.settings:charge:disp_amt" />
    </mvt:if>

    <mvt:if expr="l.settings:charge:type EQ 'DISCOUNT'">
        <mvt:assign name="l.settings:discount_amount" value="l.settings:charge:disp_amt + l.settings:discount_amount" />
    </mvt:if>

</mvt:foreach>

<mvt:comment>Remove negative from discount amount</mvt:comment>
<mvt:assign name="l.settings:discount_amount" value="abs(l.settings:discount_amount)" />

<mvt:comment>Remove tax amount from order:total</mvt:comment>
<mvt:assign name="l.settings:order_total_no_tax" value="l.settings:order:total - l.settings:tax_charge" />
Miva&mvt:global:delimiter;&mvt:order:id;&mvt:global:delimiter;Order&mvt:global:delimiter;&mvte:order:date;&mvt:global:delimiter;&mvte:order:ship_fname; &mvte:order:ship_lname;&mvt:global:delimiter;"&mvte:order:ship_city;"&mvt:global:delimiter;&mvte:order:ship_state;&mvt:global:delimiter;&mvte:order:ship_zip;&mvt:global:delimiter;"&mvte:order:ship_addr;"&mvt:global:delimiter;&mvte:order:ship_cntry;&mvt:global:delimiter;&mvte:shipping_charge;&mvt:global:delimiter;&mvte:handling_charge;&mvt:global:delimiter;&mvte:discount_amount;&mvt:global:delimiter;&mvte:order_total_no_tax;&mvt:global:delimiter;&mvte:tax_charge;&mvt:global:delimiter;&mvte:store:country;&mvt:global:delimiter;&mvte:store:state;&mvt:global:delimiter;&mvte:store:city;&mvt:global:delimiter;&mvte:store:zip;&mvt:global:delimiter;"&mvte:store:address;"&mvt:global:delimiter;&mvt:global:newline;
    </mvt:if>
</mvt:foreach>

Assign the http_headers item to the page with the following settings:

- Content-Type text/csv
- Content-Disposition attachment; filename="axjar\_order\_export.csv"

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.

Note

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:

<Module code="taxjar" feature="tax">
    <Settings>
        <NexusRegions>none|taxjar|merchant"</NexusRegions> <!-- replaces UseNexusRegions -->
    </Settings>

    <NexusRegion_Delete country_code="XX" region_code="YY" />
    <NexusRegion_Insert>
        <CountryCode>XX</CountryCode>
        <RegionCode>YY</RegionCode>
        <Zip>...</Zip>      <!-- Optional -->
        <City>..</City>     <!-- Optional -->
        <Street>..</Street> <!-- Optional -->
    </NexusRegion_Insert>
</Module>

<Module code="taxjar" feature="tax">
    <Categories_Update />
</Module>

<Module code="taxjar" feature="tax">
    <Settings>
        <APIKey>xxx</APIKey>
        <Endpoint>Sandbox|Production</Endpoint>
        <AutomaticTransactions>true|false</AutomaticTransactions>
    </Settings>
</Module>

Note

These xml functions can be used via the JSON API using: 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 Settings -> Domain Settings -> 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.

Updates & Improvements#

Miva 10.02.00 brings the following updates to the TaxJar Integration

  1. Empty transactions with no items or shipping charges are no longer created in TaxJar - This means that if you cancel an order in Miva and there are no item and no shipping cost, then when Miva issues a refund transaction to TaxJar, a new order with $0.00 will not be created.
  2. Refund Transactions now use the date of the refund vs the original order date - This makes it so that reporting in TaxJar is more accurate.
  3. If Tax on Shipping is not returned, we now fall back to the use the total tax on the order