Cratejoy offers an advanced TaxJar integration to eligible stores. It can calculate taxes, sync transactions, and sync nexus settings through a connected TaxJar account.

Advanced TaxJar Integration

The advanced TaxJar integration uses your TaxJar API token. The advanced controls appear only on stores with access to this integration. If you do not see them, you can still use the standard TaxJar CSV export.

Step 1: Install the TaxJar App

• In the Merchant Portal, go to Apps → App Store and install the "TaxJar" app.
  • Anyone may install this app, but by default, it will only provide the TaxJar export feature and provide instructions on its use. Stores with Advanced TaxJar access will see "Advanced TaxJar Integration" in the app settings.

Step 2: Configure the TaxJar App

• In the Merchant Portal, go to Apps → TaxJar. We have a full guide on how to configure the TaxJar App review the TaxJar app setup guide
• Enter and save your TaxJar API Token. We'll use this to sync your tax nexus settings from TaxJar and to calculate taxes using the TaxJar API.
• Once your API Token has been saved, you'll see three additional options:
  • Calculate Taxes Using TaxJar - when enabled, any orders will use TaxJar to calculate taxes rather than our default system.
  • Sync Transactions to TaxJar - when enabled, captured transactions and refunds are synced to your TaxJar account for nexus monitoring and tax reporting.
  • Sync Tax Nexuses - To prevent overages on your TaxJar account, we only hit the TaxJar API for orders shipping to states with a tax nexus shown.

If calculating taxes using TaxJar, be sure you show at least one state in your state nexuses on Cratejoy. Your home state is considered a nexus, and should be included.

Once configured the advanced integration allows us to use your TaxJar API token to calculate taxes and to sync all transactions to your TaxJar accounts for tax reporting purposes. To fully enable this you must enter your API token, opt in to tax calculations and/or transaction reporting, and optionally tag your products with tax codes.

Step 3: Adding Your API Token

The first thing you'll need to do is add your TaxJar API Token. You can get your API token from TaxJar following these instructions from TaxJar. Enter the 32-character token and save. Our system will validate the token to ensure it's active. If successful, you'll then have access to the remaining settings:

Step 4: Sync Tax Nexuses

To prevent unnecessary TaxJar API usage, Cratejoy only requests calculations for orders shipping to states with a tax nexus shown. In order for any tax calculations to happen, you'll need to setup at least one nexus in your TaxJar account and then use the "Sync Nexuses from TaxJar" button on the integration settings page:

You should see at least one nexus after syncing. If not, verify you have one set up in your TaxJar account.

Step 5: Calculate Taxes Using TaxJar

Enable this if you want Cratejoy checkout and renewals to use TaxJar for calculating taxes rather than using our default system. This will apply on your storefront checkout as well as for renewals and the “Charge Immediately” tool. It does not currently apply to Marketplace checkout or orders charged via the API.

Note that if we get a blocking error from TaxJar, we will fall back to our default system. If the error appears persistent, we’ll also disable the “Calculate Taxes Using TaxJar” setting and put a notice in your Merchant Portal. The most common causes of this are:

• Invalid API Token: We test your API token when saving, but if for some reason it stops working, we'll switch back to the old system.

• Bad shipping settings: A buyer giving a bad shipping address will be notified on checkout and given the opportunity to correct it, but if your store's shipping address is invalid, TaxJar will report an error. Since this cannot be correct on the buyer's end, we simply allow them to fall back to the old system and alert you to the error. If this happens, please verify that your country, state, and zip code are all correct under Settings → Shipping in the Merchant Portal.

It is strongly recommended that you do at least one test checkout after enabling this to ensure you don't have any unexpected issues.

Step 6: Sync Transactions to TaxJar

When enabled, all captured transactions and refunds on your account will be synced to your TaxJar account. This allows TaxJar to identify new tax nexuses based on sales volume.

Step 7: Add Tax Codes to Your Products

When the Advanced TaxJar app is installed, you'll have the ability to add a "tax code" to each subscription or e-commerce product. The list of available tax codes is provided by TaxJar and allows them to apply any additional taxes (or tax exemptions) for certain types of items.

You can tag individual products by going to Products → Subscription Products and Products → One-Time Products. Select the product you wish to tax and scroll to the "Tax Category" section:

Each product can be tagged with a single Tax Category. You can search the list of tax codes provided by TaxJar by typing in the input field:

Once you've selected the appropriate category, simply save the product. You can modify the selection at any time.
Note: Gift Cards will be automatically given the appropriate "Gift Card" tax code and don't need to be manually tagged.

Step 8: Verify Your Integration is Working Correctly

• Once you've configured your integration and enabled "Calculate Taxes Using TaxJar", be sure to do a test checkout.

We will not block user checkout if TaxJar reports any misconfiguration with your app, and will instead use our default system as a fallback.

If a store-wide error is encountered, we may disable the TaxJar app and flag the issue in the Merchant Portal.

Error Handling:

If the customer provides an invalid shipping address, we'll return them to checkout to correct their address.

Any other error will not block checkout. Issues with the TaxJar API or app configuration will be flagged in the Merchant Portal while still allowing customers to make purchases with the default tax calculations.

Temporary connection errors will be ignored, but any persistent errors may result in the app being disabled until corrected to avoid excessive API usage. These errors include:

• If your TaxJar API Token is invalid
• If TaxJar reports your store shipping address as invalid. This is your address under Platform Settings → Shipping and is used by TaxJar when calculating taxes.

In contrast with checkout, renewal orders will be allowed to fail, and will automatically retry the following day.

Viewing API Logs

You can see all API requests we make to TaxJar for your account at the very bottom of the settings page. This will bring up a list of API requests we've made for your account:

What API Requests Does Cratejoy Make?

Saving your API Token

We make a single test API request when attempting to save your API Token to ensure it's a valid token.

Sales Tax Calculation

We send a sales tax calculation request to TaxJar when a user is on the checkout page, has filled out their shipping details, and are in a tax nexus for your store. These results are cached, so we don't send multiple requests for the same address and cart contents.

We also will send a tax calculation request whenever charging an order, e.g. when processing renewals.

Sync Transactions

When you have "Sync Transactions" enabled, we'll send the details to TaxJar whenever a new successful transaction is recorded in our system–both for captured transactions and refund transactions.

If you issue multiple refunds on a single order, it will show up in your TaxJar account as a single refund transaction, with the total amount refunded from all refunds.

Sync Nexuses

We'll request a list of nexuses from TaxJar whenever you click the "Sync Nexuses" button in your app settings page. We may additionally do a periodic sync to ensure the list is up to date, but these will not impact your TaxJar account API limits or billing.