Custom Integrations Best Practices

To provide a deeper level of guidance, we put together this guide, where you’ll find additional best practices for our custom integration customers.

TaxJar API implementation checklist:

1. Locate your live TaxJar API token in your TaxJar dashboard under Account > TaxJar API.
2. Configure your nexus states and set “Calculate tax with TaxJar’s API” → Enabled.
3. Implement product tax codes if you have exempt products. If omitted, the item is treated as fully taxable.
4. Use the Taxes Endpoint to calculate sales tax for a given order.
5. Use the Transactions endpoint to POST an order to TaxJar using the calculation value.

Best practices for TaxJar API endpoints

Before you dive into these best practices, we encourage you to first review our API documentation.

Review Taxes Endpoint

• Ship From parameters - Though listed as optional, we recommend always providing full ship from address whenever possible, due to origin-sourced states.
• Ship To parameters - Country, zip code, and state are the minimum requirements for a Ship To address. However, we recommend always providing the full city and street for rooftop accuracy.
• amount - Amount value is only optional when you are passing line items.
• shipping - Shipping value is required, even if 0.
• nexus_addresses[] - Implementing this array will override your account State settings. Omit this array to default to your State settings (recommended).
• line_items[] - The line item array is required if you have exempt products, and otherwise strongly recommended if you have multiple items per cart to minimize penny variance in calculations.
  • line_items[product_tax_code] - Pass your product tax code as shown in the request example here. If omitted, the item is treated as fully taxable.
  • Note that product tax codes do not force your item to be exempt - TaxJar reads the product tax code, and adjusts the product taxability based on the Ship From, Ship To, and local laws.
• See the Response Example to see how the tax breakdown is returned. Use the amount_to_collect and/or the tax_collectable per line item when POSTing your transactions. The Taxes Endpoint is stateless, so you must store the values returned.

Review Transactions Endpoint

Most parameters are identical to the Taxes Endpoint, with a few key differences:

• The transactions/orders path expects positive values only, while the transactions/refunds path expects negative values.
• Use a unique transaction_id and provider value for each transaction.
• Use the transaction_date for when the transaction was originally recorded.
• amount - Amount value is now required, even when you are passing line items.
• sales_tax - Total order sales tax is required, in addition to if line items are being passed.
• line_items[] - Make sure you are passing identical line item data in the Transactions request as you are in the Taxes request.
• Do not POST a transaction until an order is considered finalized, where only a new order or a new refund would be issued. This is because we do not recommend using PUT or DELETE to change transaction records in TaxJar as it would not affect data already received by the state.
  • For example, if you plan to use AutoFile, the lock date for your sales tax reports are on the 7th of each month. Once the report locks, and you PUT or DELETE a transaction that has already been reported to the state, the state will not receive the updated data.
  • Instead, implement the TaxJar API so you are only POSTing finalized transactions and never relying on PUT or DELETE functions.

Optimize API Calls and ancillary endpoints

• Omit the Taxes API call for non-nexus states, exempt customers, and when you are 100% sure your products are fully exempt, as these scenarios will always return a $0 calculation.
  • Tip: Use the Nexus endpoint to GET your nexus regions once per day, store the values, and only call for a sales tax calculation for your nexus states in the list.
• Always POST all transaction orders and refunds - do not omit $0 sales tax collected transactions as states still want gross sales reported.
• You can use the Customers endpoint to create customers in TaxJar via the API to assign an exemption type.
• The Validations endpoint uses the USPS database, and is free to use.
• The Taxes endpoint is regularly maintained and will return the most accurate rates - we do not recommend using the Rates or Summarized Rates endpoints for the highest accuracy, as they do not have rooftop accuracy.
• Refer to our error codes if you are returning an error.

Test your integration

• Users on the Professional Plan have access to the Sandbox Environment. Please note that this environment is stateless and only meant to validate request and response formatting.
• For more robust testing, we recommend creating a new free TaxJar trial account under a different email. You can use the API key from this account for live production testing for free for 30 days.
  • To extend your testing period beyond the provided 30 days, please reach out to support@taxjar.com for an extension.

Our knowledge base and developers site are full of helpful articles for all types of customers to reference during onboarding and beyond. If you have additional questions, please reach out to our support team at [email protected].