TaxCloud API Developer Guide

Whether you’re building a custom eCommerce integration, automating exemption certificate management, or handling refunds programmatically, our API provides all the flexibility you need.

TaxCloud APIv3 Overview

This section explains the basic concepts you need to know to use the TaxCloud API.

The Cart — Tax Lookup

A TaxCloud cart is created when a user adds items into their ecommerce cart by calling the create cart endpoint.  The response from the cart includes the tax amount and rate broken out per line item as a blended rate / amount.  Multiple carts can be created on the same create cart call.  This is to support scenarios where there are multiple destination addresses or multiple customers that require calculation at the same time.

The Order — Order Capture

When a user checks out, the cart should then be transitioned into an order using the create order from cart endpoint.  The completed order concept is used to show an order was fulfilled and the tax is now ready to be filed for the order.  Completing an order can be done at the time the cart is transitioned to an order, or later using the update order endpoint to set that completed date.

After an order is completed you have the option to apply refunds against the order.

TICs (Taxability Information Codes)

TICs are a code that tells the TaxCloud engine whether the items should be taxable or not depending on the destination address of the sale, allowing an item or a service sold to have accurate tax rates applied.  Each line item on an order and a cart has the ability to have a unique TIC.

Product Catalog TIC Mapping

Instead of including the TIC for each product in the cart/order, it is possible to create mappings between product codes and TaxCloud TICs for a given connectionID. These mappings apply to all orders for that connectionID.

Exemption Certificates

An exemption certificate is required if the customer is tax exempt.

Order level exemption certificates can be applied to a cart or order for an exempt customer.  There are two ways to have an exemption certificate applied to a cart/order; both require the exemption certificate to exist prior to the endpoint call.  

• Option A: Attach the exemption certificate to the request. The ids for exemption certificates are in the form of GUIDs, and can be added to the create order/cart request at exemption.exemptionId.  
• Option B: Allow the system to automatically match a pre-existing certificate to the cart/order. Set the exemption.isExempt field is true on the cart/order, and the certificate will be auto-matched if the connection, customerId, destination state match the order and the certificate is not disabled.  If no certificate can be found, the order will be marked as exempt with no certificate.  These certificates will be required at a later date.

API Reference

There are two TaxCloud APIs.

• Sales Tax API: Used to estimate taxes, capture orders, and manage exemption certificates.
• Management API: Used to manage keys and Product Catalog TIC Mapping. This API is currently only accessible if you use your JWT token from the TaxCloud app. API key access will be available in the future.

Authentication

To use the API, you need an API key as well as a connection ID for a custom API integration connection.

1. Create a TaxCloud free trial. 
2. In TaxCloud, generate an API key at Developer > API. You'll need this key to connect to the API.
3. In TaxCloud, create a Custom API integration on the Integrations page.
4. Copy the ConnectionID for the custom API integration you created.