By default, Cratejoy uses ZipTax to calculate taxes. We're developing an alternative integration using TaxJar, which is currently only available for limited beta access.

Advanced TaxJar Integration

The advanced TaxJar integration will allow you to use your TaxJar API Token to calculate taxes on checkout. This feature is currently in beta and not available to all sellers.

Step 1: Install the TaxJar App

• In the Seller Dashboard, 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 special beta access will see "Advanced TaxJar Integration" in the app settings at the bottom.

Step 2: Configure the TaxJar App

• In the Seller Dashboard, go to Apps->TaxJar. We have a full guide on how to configure the TaxJar App here
• 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.
  • [Not yet available] Sync Transactions to TaxJar- when enabled, all transactions on your account will be synced to your TaxJar account. This allows TaxJar to identify new tax nexuses based on sales volumes.
    • This feature will be available in the coming weeks. Until then, you can use the TaxJar export or manually add nexus states to your TaxJar account.
  • 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 on your TaxJar account, we only make a request to the TaxJar API 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 seller 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 Seller 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 Seller Dashboard.

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