Integration Basics

Getting started with TaxCloud Integration

Before integrating with the TaxCloud API, you’ll need to set up your TaxCloud account and understand a few concepts about how orders flow through TaxCloud.

System Requirement for Integration

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

  • Securely store and use your TaxCloud API credentials.
  • Assign a cartID to every customer shopping cart before checkout.
  • Send API requests and handle responses from TaxCloud.
  • Apply TICs (Taxability Information Codes) for items and shipping.
  • Handle discounts and exemptions properly before calculating sales tax.

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 > Integrations > Your connection area. You’ll find your API credentials for each individual connections in them.

Use best practices your platform provides to properly secure your API ID and Key when you interface with the TaxCloud API.

Understanding the TaxCloud Integration Flow

Integrating TaxCloud into your checkout process involves a few core steps. Each step builds on the last, ensuring your system collects the right data, applies the right rules, and calculate the correct tax amount.

Please see the end-to-end order flow for integrating with TaxCloud below, as we explain some key concepts along the way. For detailed API reference, please see our reference here.

Creating CartID

Every checkout sequence in TaxCloud begins with a cartID—a unique identifier that links all tax-related operations to a specific shopping cart. The cartID ensures TaxCloud can associate the correct Lookup (tax calculation) and Capture (finalization) requests with the right cart.

  • Assign a unique cartID as soon as the customer begins checkout.
  • Use the same cartID consistently across all subsequent API calls in that checkout flow.

TaxCloud supports two forms of cartIDs: Explicit (assigned by your system) and Passive (generated by TaxCloud). For more details, see What is a cartID?.

Creating an Order

An order in TaxCloud represents the full transaction record that sales tax will be calculated on and, eventually, reported. Think of it as the container that holds all the components of a customer’s purchase. Building an order correctly is critical because TaxCloud can only calculate and track sales tax if it has a complete picture of what’s being sold.

Order Components

When you create an order, you need to include:

  • Line items → each individual product in the cart.
  • Shipping → always treated as its own line item, with its own Taxability Information Code (TIC).
  • Discounts → applied at either the item level or the order level before tax calculation.
  • Exemptions → if the customer qualifies, linked to the order through an exemption certificate.

This structure ensures every taxable (or exempt) element of the transaction is represented properly.

Assigning Taxability Information Codes (TICs)

Because states tax goods and services differently, every item in an order needs a Taxability Information Code (TIC). The TIC tells TaxCloud how that item should be taxed in the destination state.

Assigning TICs

  • The most efficient approach is to assign TICs at the product category level, so that all products in that category inherit the same TIC.
  • When needed, you can set per-product overrides for exceptions.

See the full list of TICs here: TaxCloud TIC reference.

Shipping and TICs

Shipping must also be assigned a TIC, since it’s taxable in some states and exempt in others.

  • 11010 → if shipping charges are based on the actual cost (as shown on the shipper invoice).
  • 11000 → if shipping charges are padded or applied as a flat rate (not tied directly to actual cost).

Default TICs

If a Lookup request does not include a TIC for a line item:

  • TaxCloud will use the store’s default TIC (set in TaxCloud > Integrations > Your Connection).
  • If no default TIC is set, TaxCloud will apply the general goods category (00000), which is always taxable.

Keep TICs Current

States frequently update sales tax categories. Developers should not cache TIC definitions. TaxCloud provides real-time feeds with the latest TIC information for use in your UI/UX or selection tools.

Applying Discounts (if applicable)

Sales tax is calculated based on the final sales price—the amount the seller sets after all discounts or coupons are applied. By statute, “sales price” generally means the total consideration exchanged between buyer and seller (cash, credit, property, or services).

Key Principles

  • Discounts must be applied before calculating sales tax.
  • The way discounts are applied across items is a business decision for the seller, since each item may be taxable or exempt.

Discount Application Methods

Sellers may choose from several common methods:

  1. Evenly → Divide the discount equally across all items.
  2. Proportionally → Allocate discount based on each item’s price relative to the cart total.
  3. Sequentially → Reduce item prices one at a time until the discount is fully applied.
  4. Preferentially → Apply discounts to exempt items first, or taxable items first.

Best Practices

  • Decide and document your discount methodology.
  • Ensure your e-commerce platform or integration implements it consistently.
  • For transparency, disclose your methodology in a Discount Application Policy.

Attaching Exemption Certificates (if applicable)

By default, TaxCloud applies sales tax to every transaction unless a valid exemption certificate is on file. An exemption may apply because:

  • The item itself is exempt in the customer’s jurisdiction (TaxCloud detects this automatically using TICs), or
  • The customer is exempt (e.g., government agencies, schools, religious institutions, resellers).

To prevent tax from being charged, sellers must provide a TaxCloud-issued exemption certificate ID during tax calculation. If a certificate is incomplete or invalid, TaxCloud will apply sales tax and return a warning.

During each Lookup request, TaxCloud checks the exemptCert parameter:

  • If a valid certificate is already on file, customers do not need to resubmit the full form.
  • Customers must still be able to select which of their available certificates to apply.

Types of Certificates

  • Single-Purchase Certificate: Valid for one transaction only. A complete certificate must be submitted before use.
  • Entity-Based Certificate: Covers all purchases for a customer. Must be completed and stored in TaxCloud first. Once issued, TaxCloud assigns a certificate ID, which is all that’s needed for future calculations.

Required Information

To complete a certificate (single-purchase or entity-based), sellers must collect:

  • Purchaser name and address
  • Tax ID (FEIN or SSN)
  • Business type
  • Reason for exemption
  • Affected states (with reason for exemption and the state-provided exemption ID).

Once all discounts are applied and the revised sales price is determined, send a Lookup API request to TaxCloud. This ensures the tax is calculated accurately based on the discounted order total.

Sending Lookup API request

Once the cart is built with all components—line items (each with a Taxability Information Code, or TIC), shipping (as its own line item), discounts (applied at item or order level), and any applicable exemptions—you’re ready to calculate sales tax.

Send these details to the Lookup API. TaxCloud evaluates the order against destination-based rules, exemptions, discounts, and item-level TICs. The response includes the precise tax amount per line item, ensuring accuracy at checkout and preparing the transaction for order completion and reporting.

Completing Order

When the order is finalized and ownership of goods or services is transferred, order must be marked as complete in TaxCloud. This is done using the Authorized, Captured, or AuthorizedWithCapture APIs. Completing the order ensures that the tax is properly recorded and included in TaxCloud’s reporting and filing for that period.

Important: If you don’t complete the order, the transaction will not be reported and your tax filings will be incomplete.

Integrating with TaxCloud ensures that every step of the checkout process—cart creation, tax lookup, and order completion—is accurately captured for compliance. By securely managing API credentials, building orders with all taxable and exempt components, and finalizing transactions through the required completion APIs, your platform guarantees that sales tax is calculated, recorded, and reported correctly. Following these practices streamlines tax management and also protects your business from filing errors and compliance risks.