Getting Oriented with TaxCloud

Table of Contents

  1. Overview

    1.1 Components

    1.2 API Endpoints

    1.3 How Does TaxCloud Work?

    1.4 Testing

  2. Integrating TaxCloud

    2.1 Prerequisites

    2.2 Taxability Information Codes (TICs)

    2.3 API IDs and API Keys

    2.3 CartIDs

    2.4 Exemption Certificates

    2.5 Discounts

  3. Conclusion

1. Overview

Welcome to the TaxCloud Developer Orientation Guide. This guide is for developers who want to integrate TaxCloud with an e-commerce system, order management system, point of sale system, or any other invoice or transaction management platform that needs to calculate sales tax (or manage exemption certificates for exempt purchasing entities). Before getting started, you should check our Partner Integrations area to see if the platform you are targeting has already been implemented.

All of the documentation in our TaxCloud Developer Center extremely technical. If you’re looking for general information on setting up and using TaxCloud, please visit our main TaxCloud Support area.

1.1. Components

TaxCloud consists of:

  1. A set of easy-to-use Application Programming Interfaces (APIs) that can be used by e-commerce platforms, online marketplaces, and ERP or POS systems, and;
  2. Our TaxCloud website, where you can configure account settings (such as where you want to collect sales tax), as well as review transaction records and automatically generated sales tax reports with full jurisdiction and sub-jurisdiction detail.

Our APIs and our website work together to make it easy for a business of any size to collect, report, and remit sales tax, with minimal operational or development effort.

For TaxCloud to work properly, the minimum implementation should include the following APIs (presented in order of operation):

  1. VerifyAddress
  2. Lookup
  3. AuthorizedWithCapture
  4. Returned

1.2. API Endpoints

  • SOAP/XML clients access our TaxCloud API endpoint: https://api.taxcloud.net/1.0/
    • SOAP/XML WSD is available at: https://api.taxcloud.net/1.0/TaxCloud.asmx?wsdl
  • JSON/REST clients access our TaxCloud API endpoint https://api.taxcloud.net/1.0/TaxCloud/{method}
    • {method} is the TaxCloud API method to call.
    • For example the url to execute the Ping method is https://api.taxcloud.net/1.0/TaxCloud/Ping

1.3. How does TaxCloud work?

There are four basic steps in TaxCloud’s process, as outlined below.

  1. Address Verification (API: VerifyAddress): Make a commercially reasonable effort to ensure the address the customer has provided is complete. If your system already uses a third-party (or internal) address verification system, you can skip this step.
    IMPORTANT: If address verification fails to return a more accurate address, the transaction process should proceed to Lookup using the customer provided address.
  2. Tax Amount Lookup (API: Lookup): 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 exact dollars and cents of tax proceeds due for each line item.
    NOTE: Our Lookup API does not respond with tax rates or jurisdiction/sub-jurisdiction details. Why?
    • Providing rates would require developers to do math, respecting varied rounding rules and knowledge of varied caps and thresholds.
    • Providing jurisdiction details would add payload unnecessary for time-of-sale tax collection—jurisdiction details are needed for tax reporting and are automatically included in standard TaxCloud tax reports and transaction records available from the TaxCloud website.
  3. Order Completion (APIs: Authorized and Captured; or AuthorizedWithCapture): Notify TaxCloud that the customer has completed her purchase and that the store has collected the sales tax due.
    IMPORTANT: Order Completion is REQUIRED to ensure a transaction is included in the sales tax reporting for the period.
  4. Merchandise Returns (API: Returned): This step occurs when an order is cancelled or modified after it was completed (after Order Completion).

    • If the Returned API is called in the current period, it will cancel-out the tax remittance for the period.
    • If the Returned API is called in a subsequent period, TaxCloud will automatically record the tax credit amount(s) for each jurisdiction of record, and automatically apply such credits to reduce future tax remittances to each applicable jurisdiction.
    PRO TIP: The Returned API allows specification of a ReturnedDate. UNDER MOST CIRCUMSTANCES THIS PARAMETER SHOULD NOT BE USED. Without specifying the ReturnedDate parameter, the Returned API defaults/infers the ReturnedDate based upon the date the API is called. This is the correct behavior, from a tax perspective.

     

    For example: If you had accepted and completed an order in February, and the order was returned in April, any sales tax due would have been reported and remitted with the February sales tax return.
    • Without specifying the ReturnedDate parameter, TaxCloud will automatically recognize the sales tax was previously remitted, and create a credit automatically reducing the tax proceeds due for the current period. This is usually the intended and preferred result.
    • However, if you pass the ReturnedDate parameter using the date of the original sale (or any date outside the current period), TaxCloud will recognize this as a change to the previously filed sales tax return, triggering an Amended Sales Tax Return to be generated and filed, including every intervening sales tax return from the period of the original sale to the current period. This will incur Late or Amendment Fees from TaxCloud, as well as filing obligations and charges from your CPA or accountant if TaxCloud is not filing on your behalf (via Automated Compliance). This should be avoided, unless your accountant or tax counsel has advised you to do this.

1.4. Testing

There’s no need to create a separate test account with TaxCloud. Every account is in test mode until a "store" (a set of API Credentials) associated with the account goes live. This way, no changes need to be made to your code when you are finished testing and want to go live, and you do not need to have multiple TaxCloud accounts to accommodate development or testing alongside live production use.

2. Integrating TaxCloud

Before you get started, you’ll need to register for a new TaxCloud account.

Note: if you are a developer setting up TaxCloud for a client, the Company Name during registration should be your client's company name.

2.1. Mechanical Prerequisites

To integrate TaxCloud successfully, your environment will need to perform the technical following feats:

  • Securely obtain all the information required to perform each API call
  • Securely persist a "CartID" to be used for each subsequent API call for a particular customer checkout sequence
  • Initiate secure SSL connections from your system to TaxCloud
  • Receive and parse API responses from TaxCloud

2.2. Assigning Taxability Information Categories (TICs)

Different categories of goods are taxed differently by different states. To make sure an item is taxed at the correct rate, you’ll need assign it a Taxability Information Code (TIC) for each item being sold. Rather than requiring tedious per-product TIC assignment, efforts should focus on assigning TICs to existing system product categories, allowing all products contained is such categories in inherit the TIC assigned to the category, and accommodating per-product "overrides" when set for particular products within the category. Detailed documentation regarding TaxCloud TICs is available at https://taxcloud.com/tic.

IMPORTANT: Shipping, too, needs to be assigned a TIC, as it’s taxable in some states and exempt in others (and in some states the tax treatment of shipping is based on the items being purchased).
  • If your system charges customers for shipping based upon the actual cost incurred by the seller (as can be evidenced by shipper invoice), then the correct TIC is 11010.
  • If your system "pads" the actual shipping cost, or uses "flat rate" shipping charges (regardless of actual cost), then the correct TIC is 11000 (Shipping and Handling).

2.2.1. Default TICs

If a Lookup request does not provide/submit a TIC for a line item, TaxCloud will calculate sales tax based on the store's default TIC, which can be set in the TaxCloud > Settings > Stores area. If no default TIC has been set, TaxCloud will calculate the sales tax using the “general goods” tax category (TIC 00000 which is always taxable).

IMPORTANT: States frequently update their sales tax laws, including sales tax categories. For this reason, developers should not cache TIC definitions. TaxCloud provides various real-time feeds with the most current TIC information that can be used for dynamic selection and assignment for a system's UI/UX features.

2.3. API IDs and API Keys

All calls to TaxCloud are authenticated using a set of API Credentials consisting of a unique API ID (or apiLoginID) and API Key. Both the API ID and API Key are found in the TaxCloud > Settings > Stores area,

NOTE: 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/update the replacement API Key to the store's configuration quickly so that TaxCloud continues working on the website.

PRO TIP: Copy and paste your API ID and Key into your source code where you are calling TaxCloud to prevent human error, for instance, mistakenly transcribing a zero (0) as alphabet capital character (O).

2.4. 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 calculates the tax amount due) with the right customer shopping 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 (see What is a cartID).

2.5. Exemption Certificates

TaxCloud applies sales tax to every transaction unless a valid tax exemption certificate is identified and on file. An item may be exempt from sales tax in the customer’s location, which TaxCloud automatically recognizes. Or the customer may be exempt—government purchasers, schools or religious institutions, and 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 a valid TaxCloud-issued exemption certificate ID must be supplied. If an 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 Lookup API request. 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.

2.5.1. 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.

2.5.2. 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.

2.5.3. 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.

More information on exemption certificates requirements are available in our AddExemptionCertificate API documentation.

2.6. Discounts

The term "Sales Price" is defined by statute in every state as essentially (paraphrasing because each state has its own unique version):

"Sales price" means the total amount of consideration (including cash, credit, property, and services) exchanged between a purchaser and a seller to effectuate a transaction to both parties satisfaction. (emphasis added)

The important point is that Sales Price is set by the Seller, after discounts or coupons are applied. Once the Sales Price is set by the seller, the amount of tax due can be calculated.

For absolute clarity: Any and all seller-provided discounts must be applied to the Sales Price before calculating sales tax.

Because each item may be taxable or exempt, when a discount is applied, the methodology of exactly how that discount is applied is a relevant business decision for the Seller.

For example, does the Seller apply the discount:

  1. Evenly: DiscountDollars divided by AllItemsCount (easiest) or
  2. Proportionally: LineItemSalesPrice divided by AllItemsSalesPrice multiplied DiscountDollars, or
  3. Sequentially: Reducing the LineItemSalesPrice of an item down to zero, if additional DiscountDollars remain, continue through each additional line item until DiscountDollars is exhausted, or
  4. Preferentially: Exempt items before the taxable items, or vice-versa
NOT TAX ADVICE: DO NOT CHOOSE OPTION 4 (Preferentially)

Sellers should choose their preferred methodology and ensure their developer or e-commerce platform incorporates it accurately.

Developers should include detailed comments in their source code about their implementation of the chosen Discount Application Policy.
BEST PRACTICE: Sellers should disclose their methodology to customers in a Discount Application Policy.

Finally, after any and all discounts have been applied and the revised Sales Price has been determined, the tax Lookup API call should be sent to TaxCloud so we can calculate the amount of sales tax due.

3. Conclusion

We recognize most developers will never read through this entire document in a sitting—that's OK. At least it's all in one place.