Description
TaxCloud is a sales tax management service for retailers in the USA. It calculates the sales tax due for each order, records the transactions and prepares the reports used to file the tax. You can read more about the services it offers on its website: https://taxcloud.net/
HikaShop includes a TaxCloud plugin (a Joomla plugin of the hikashop group, named "Hikashop TaxCloud Plugin"). It is installed with HikaShop, but disabled until you configure it. It requires the SOAP PHP extension on your web server.
Once it is configured, the sales tax shown to your customers in the cart and at checkout comes from TaxCloud instead of the tax rules of HikaShop, for orders shipped to a United States address. When the order is confirmed, the plugin sends the transaction to TaxCloud, and when you cancel a confirmed order, it tells TaxCloud about the refund.
Getting a TaxCloud account
The steps below are on the TaxCloud website, so their wording can change over time. The TaxCloud user guide is the reference for them: TaxCloud User Guide.
1-Create a TaxCloud account at taxcloud.net and confirm your registration by email.
2-In the "Location" menu, click on "add store/office" and fill the form with the address your orders are shipped from. Make sure the address is verified by USPS (button "check address USPS").
3-In the "Website" menu, click on "add Website" and fill the form with the information of your website. Your HikaShop store may already have been added when you registered.
4-Copy the API ID and the API key of your website. They can be found in your TaxCloud account on the "Websites" page. Please do not share these credentials with anyone else or use them for multiple URLs.
5-Set a Default TIC (Tax Information Code) for your store within TaxCloud, so your customers are charged the correct rates and benefit from any available exemptions. The complete list of TICs is in the "Taxability Codes" section of your TaxCloud account.
6-Select the states where you want to collect sales tax in your TaxCloud account.
The plugin also needs a USPS WebTools ID (the "USPS Id" setting) to verify your customers' addresses. To get one, go to USPS.com/webtools and click "Register Now", and the ID is sent to you by email.
Enabling and configuring the plugin
1-In the Joomla administration, go to System > Plugins (Manage > Plugins on Joomla 4 and later) and search for "TaxCloud".
2-Open the plugin "Hikashop TaxCloud Plugin", fill the settings described below, set its Status to Enabled and save.
3-Open the plugin again and click on the "Check address" trigger to check your store address (see below).

Until both the API Id and the API key are filled, the plugin does nothing, and the backend shows the message "Please configure your TaxCloud plugin via the Joomla plugins manager".
Plugin settings
API Id: the API ID given by TaxCloud.
API key: the API key associated to that API ID.
USPS Id: your USPS WebTools ID, used to verify the addresses.
Address 1: the first line of the address of your store/office (where your orders are shipped from). Use the same address as in your TaxCloud account.
Address 2: the second line of that address.
City: the city of your store/office.
State: the state of your store/office, as its two letters code (for example IL).
Zip4: the 4 digits extension of the ZIP code of your store/office.
Zip5: the 5 digits ZIP code of your store/office.
Check address: the "Trigger" link sends the address above to USPS and shows a table with the original values and the processed values. Save the plugin before you click on it, as it checks the saved values. If the processed values differ from the original ones, enter the processed values in the settings instead. It requires the USPS Id.
Use origin address on override: some shipping methods override the shipping address of the customer, for example a local pickup at your store. With this option set to Yes (the default), the origin address above is then used as the destination address for the tax calculation. With No, the plugin skips the TaxCloud calculation in that case and HikaShop uses the tax rules you configured in the backend.
Exemption flag column: use it if some of your customers are exempt of taxes. Create a custom field of the table "user", of the type single dropdown or radio, with the values yes and no (or 1 and 0), and with its frontend display turned off. Enter the column name of that field here. Then edit the exempt customer in the HikaShop backend and select yes (or 1) in that field: no tax is calculated for that customer.
Default TIC id: the TIC used for the products that have no TIC of their own. For general goods and services, the TIC is 00000.
Shipping TIC id: the TIC applied to the shipping fees, if you charge your customers for shipping (usually 11010).
Setting a TIC on your products
When the plugin is enabled, the product edit page of the HikaShop backend has a new field named "Product Taxability Code", in the "Custom fields" block. Enter the TIC of the product in it (a number) and save the product. If it is empty or 0, the Default TIC id of the plugin is used. Variants use the code of their main product.

For a large number of products, you can set the code in bulk with the Mass actions of HikaShop (menu System > Mass actions) or with the CSV import (menu Products > Imports), using the product_taxability_code column of the product table.
What happens at checkout and on orders
1-Once the customer has chosen a shipping or billing address in the United States, the plugin verifies it with USPS, then asks TaxCloud for the tax of the cart. The result replaces the HikaShop taxes in the cart, in the shipping prices and at checkout, with a line named "Tax (x%)".
2-When the order is created, the plugin sends a new request to TaxCloud with the number of the order.
3-When the order reaches a confirmed status (the statuses of the "invoice order statuses" setting of HikaShop, confirmed and shipped by default), the transaction is captured in TaxCloud. Captured transactions are included in the reports TaxCloud generates for your tax filing.
4-When you cancel an order that was confirmed (the cancelled order status of HikaShop), the plugin sends a return of the whole order to TaxCloud. When you return only some of the products of an order in the backend, a partial return is sent, with each product using its own TIC.
Testing and going live
Try some test orders before you go live. The order must be completed, it is not enough to add an item to the cart. Then change the status of the order to a confirmed status in the HikaShop Orders page, log in to TaxCloud and open the "Transactions" tab. Open the transaction and check that it matches the HikaShop order.
TaxCloud stays in test mode until you set your account to live. When you are ready, log in to TaxCloud, go to the "Websites" page and click on the "Go Live!" button. If it is not displayed, TaxCloud tells you what is missing.
Limits
- Only orders shipped (or billed, when there is no shipping address) to a United States address are calculated by TaxCloud. For any other country, the HikaShop tax rules apply as usual.
- Exempt customers (see the Exemption flag column setting) are not calculated by TaxCloud.
- The calculation is made once a customer is logged in or registered and has an address selected.
- If TaxCloud cannot be reached or refuses the request, the message "TaxCloud error" followed by the reason is displayed, or "Unknown error. The tax calculation service is probably down." when there is no reason. The same message is only displayed once per page. Check the taxes of the cart in that case before accepting orders.
- The transactions of orders created from the backend are not sent to TaxCloud when they are created.
Troubleshooting
The taxes of HikaShop are still used: check that the plugin is enabled, that the API Id and API key are filled, and that the address of the customer is in the United States.
"Please configure your TaxCloud plugin via the Joomla plugins manager": the API Id or the API key is empty.
"The HikaShop TaxCloud plugin requires the SOAP PHP extension...": ask your hosting company to enable the SOAP PHP extension, or disable the plugin.
"Wrong shipping address": USPS could not verify the address entered by the customer at checkout. The customer has to correct it. If it happens for all addresses, check your USPS Id.
"TaxCloud error : ...": the message comes from TaxCloud. A typical cause is a wrong API Id or API key, or a website not registered in your TaxCloud account.
The Check address trigger shows "Check Address Error": the address or the USPS Id is wrong. Save the plugin first, as the check uses the saved values.
A refund does not appear in TaxCloud: the order must have been in a confirmed status before it is cancelled. A "TaxCloud Error" message is displayed in the backend when TaxCloud refuses the return.