Getting Oriented With TaxCloud
Welcome to the TaxCloud Developer Guide. This guide is for developers who want to integrate TaxCloud with a custom e-commerce solution or an e-commerce solution that hasn’t yet been integrated with TaxCloud. (For a list of e-commerce solutions that already offer TaxCloud, see the TaxCloud Partners page.)
Why Should You Use TaxCloud?
- Sales tax can be challenging to manage on your own. There are more than 10,000 sales tax jurisdictions in the Unites States.
- We are sales tax experts. Our team is comprised of former e-commerce retailers, as well as former state revenue officials. Unlike other tax platforms, we know what you want (fast and reliable sales tax information, ideally for free), and we know what the states want (everyone collecting and filing their tax correctly).
- Build your business. Let us do your taxes. Before TaxCloud, keeping up with every possible sales tax rate and product-type and use-based exemption rule in every state required your business to either hire a small army of tax attorneys and software developers, or license expensive enterprise-class tax compliace platform.
- Rock solid and flawless. We have only been offline for 34 seconds since our launch of TaxCloud in 2010, and in our last audit with the states, covering thousands of merchants over a three-year span, we had zero errors.
- And with TaxCloud, you can configure your account so the states pay for our service, making TaxCloud free for you. Our business model is different from other sales tax service providers. We believe that states should pay the cost of sales tax compliance, or at least subsidize that cost. That's why we have contracted with 24 states - with more on the way - to give you the option to have them pay for TaxCloud.
How Does TaxCloud Work?
There are four basic steps in TaxCloud's process
- [x] 1. Address verification (API: VerifyAddress): To ensure the most accurate sales tax jurisdiction(s) can be identified, your customer's address should be verified before being included in a Lookup API request. You can use your own address verification system/service, or you can use our VerifyAddress API.
- [x] 2. Tax Amount lookup (API: Lookup): When your system asks TaxCloud to determine the sales tax amount due for each item the customer is purchasing, based on the address provided in step 1, TaxCloud responds with the total amount of sales tax due for each item in the transaction.
- [x] 3. Order completion (APIs: Authorized and Captured; or AuthorizedWithCapture): Your system lets TaxCloud know that the customer has completed his or her purchase and that the store has collected the sales tax due on the transaction.
- [x] 4. Merchandise returns (API: Returned): This step occurs when an order is cancelled or modified after it was completed (after the Captured call). Once a return is initiated through the store's cart admin panel, the store alerts TaxCloud and we modify our transaction records accordingly.
Development & Testing Considerations
Q: Do I need to create a test account?
A: No. There's no need to create a separate test account with TaxCloud. Every account is in test mode until a website's API credentials associated with the account "go live" (by pressing a "Go Live" button in TaxCloud). You can associate as many websites with your TaxCloud account as you want, and each will be given a unique set of API credentials. Once a website is marked as Live in TaxCloud, all transactions from that point forward will be included in our automatically generated (and optionally filed) sales tax returns and reports. All of your development and staging websites that are not marked as Live will behave exactly like your Live production websites, but those transactions will never be included in any sales tax returns or reports.
Q: Does TaxCloud have a staging system?
A: No. In our prior lives at e-commerce companies we noticed with disturbing regularity that staging environments tended to behave differently than production environments - and we hated that. So with TaxCloud, there is no staging enviroment. You always get our "best juice" regardless of whether your website has gone live - and there will be no code changes necessary to go live.
Before you get started, you’ll need a TaxCloud account (if you are a developer setting up TaxCloud for a client, the account should be your client's).
To integrate TaxCloud with a business's website, you will need to use or develop a shopping cart application that:
- securely obtains all the information required to process a transaction (including any data requirements you specify)
- initiates a secure SSL connection from your web server to TaxCloud to pass transaction data in name/value pairs
- receives and parses the transaction response from TaxCloud to display the results to the customer
Assigning Tax Categories
Different categories of goods are taxed differently by different states. To make sure an item is taxed at the correct rate, you’ll need to assign it a Taxability Information Code (TIC) through the business's e-commerce platform or shopping cart. Shipping also needs to be assigned a TIC, since it's taxable in some states. In most cases, you can assign TICs to individual items or to groups of items. More information on TICs is available in our TaxCloud Retailers Guide and at https://taxcloud.com/tic/.
There are several pieces of this component that can be configured for your own environment if you host this file locally. Please review the comments included within the file for more information.
If the business's website does not submit a line item field for the TIC, TaxCloud will calculate the sales tax based on the store's default TIC, which can be set for each associated website in the TaxCloud Websites area. If you have not set a default TIC for the store, TaxCloud will calculate the sales tax using the “general goods” TIC 00000.
IMPORTANT: States periodically update their sales tax laws, including sales tax categories. TaxCloud provides CSV, JSON, JSONP, TEXT, and XML feeds so your environment can rely upon the most current TIC information possible.
API IDs and API Keys
All calls to TaxCloud are authenticated using the unique API ID (also called the API LoginID) and API Key TaxCloud assigns to each website. Both the API ID and API Key are found in the Websites area, listed in each website's panel.
If you ever need to generate a new API Key, you can click "Reissue API Key." But as soon as you do, the previous key will be disabled. So if the store has already gone live, you will want to add the replacement key to the store's shopping cart quickly so that TaxCloud continues working on the website.
Copy and paste the API ID and Key into your source code where you are calling TaxCloud.
Cart Identifiers (CartIDs)
TaxCloud requires a customer’s shopping cart to be assigned a unique identifier before checkout. That way, TaxCloud can later connect the right Lookup (which finds the tax rate) with the right customer’s cart.
This cart identifier (CartID) should be used throughout a customer’s shopping experience, including checkout.
TaxCloud recognizes two forms of CartIDs: Explicit and Passive.
An Explicit CartID (Preferred) is usually the unique identifier automatically generated by the shopping cart system when a new customer cart is created. If the shopping cart does not automatically create an identifier, you can use any GUID-generating algorithm to create one. There are two requirements for implementing Explicit CartIDs:
- The shopping cart system must generate a unique cart identifier before a transaction is completed.
- You must have the ability to persist (via server-side database or client-side cookie) and reassociate the CartID for each unique customer session.
A Passive CartID can be used if the shopping cart system is unable to supply a unique identifier before checkout. The initial lookup can include an empty CartID parameter and TaxCloud will generate a unique CartID for the shopping cart system to use in all subsequent requests for the customer’s cart. The only requirement for implementing Passive CartIDs is that the shopping cart system must have the ability to persist (via server-side database or client-side cookie) and reassociate the CartID for each unique customer session.
TaxCloud applies sales tax to every transaction unless a tax exemption is identified. An item may be exempt from sales tax in the customer’s location, which TaxCloud automatically recognizes. Or the customer may be exempt—resellers, for instance, are usually exempt from paying sales tax.
TaxCloud can be set up so that tax-exempt customers are not charged sales tax, but an exemption certificate must be supplied. If the exemption certificate is not complete or has invalid information, tax will be applied to the transaction and a warning will be returned.
TaxCloud reviews the exemptCert parameter for every transaction. If the customer has already provided an exemption certificate (identified by exemptCert), then he or she does not need to resubmit the complete form. However, the available exemption certificates for that customer do need to be listed so that he or she can select the right one.
There are two types of customer exemption certificates: single-purchase and entity-based.
- Single-purchase exemption certificates Single-purchase certificates are good only for a single purchase. A complete certificate must be filled in before it can be used.
- Entity-based exemption certificates Unlike single-purchase certificates, entity-based certificates must be completed and stored in TaxCloud before they can be used. TaxCloud assigns each entity-based certificate a certificate ID. The certificate ID is the only thing that is needed for a tax calculation
Filling out an exemption certificate
To complete either kind of exemption certificate, the following information is needed:
- Purchaser name
- Purchaser address
- Tax ID (either the Federal Employer Identification Number or Social Security Number)
- Type of business
- Reason for exemption
- Affected states. Each state needs the reason for the exemption and the exemption ID provided by the state.
Discounts and Promotions
TaxCloud does not natively support discounts or promotions. What this means is that if you are offering your customers a discount, you must call the TaxCloud Lookup API after the discount is applied. This might mean that you need to do a Lookup call twice: once before and then again after a discount code is entered by the customer.
It is important that the discounts are applied to each item and not as a separate line item on the checkout page. For example, let’s say you have a promotional offer of $10 off a $50 order. If your customer purchases two items totaling $50 (each with a sales price of $25), you will need to divide the $10 discount between those items (adjusting the sales price for each item to $20). After the discount has been applied, you will pass the discounted sales price for each item to TaxCloud. TaxCloud will respond with the correct sales tax due for each item, based upon the discounted sales price.
Just to be clear: Discounts and coupons must be applied before sending a Lookup to TaxCloud so sales tax can be determined.