WorkflowsOrder Upload

Handling Taxability

Accurate tax calculation depends heavily on how each item in an uploaded order is classified for tax purposes. TaxCloud uses Taxability Information Codes (TICs) to determine whether and how an item should be taxed based on state and local rules. When uploading orders using the Create Order endpoint, you are responsible for explicitly specifying the taxability of each line item.

This section explains how to manage taxability in uploaded orders using TICs, manual tax overrides, and exemption configurations to ensure your order data is accurate and compliant.

Assign a TIC to Each Line Item

You can explicitly assign each item in the lineItem array a TIC (Taxability Information Code). This code tells TaxCloud what kind of product or service is being sold and determines how the item was taxed across different jurisdictions, particularly the destination jurisdiction.

1"lineItems": [
2  {
3    "index": 0,
4    "itemId": "item-1",
5    "price": 10.75,
6    "quantity": 1.5,
7    "tax": {
8      "amount": 1.31,
9      "rate": 0.08125
10    },
11    "tic": 0
12  }
13]
  • The TIC is an integer value corresponding to a predefined product category (e.g., clothing, groceries, software).
  • Always assign a TIC at the lineItem level, as this overrides other defaults. However, you can also use the TaxCloud product catalog to set your product-level TIC defaults.
  • If omitted, the default TIC during your account integration will be used. This may not be appropriate for all items and can lead to incorrect tax results if you sell multiple item types.
  • You can browse the full list and descriptions in TaxCloud’s TIC Reference Guide.

Best practices for assigning TICs

  • Define TIC mappings in your product catalog and enforce TIC validation during data ingestion or prior to order upload.
  • If most products are taxable at the normal rate, set the default TIC = 0 and override as needed.
  • If most products fall into a specific category, set that category’s TIC as the default and override for exceptions (for example, use TIC 0 for fully taxable products).

Uploading Pre-Calculated Tax

The upload flow allows you to include pre-calculated tax.amount and tax.rate for each item. These values are typically passed from an external tax system that has already determined the tax.

Important caveats to note include the following:

  • Ensure the originating system’s tax rates and amounts are as accurate as possible.
  • TaxCloud will recalculate taxes before reporting and filing. This ensures compliance and accuracy.
  • If there’s a difference between what was collected and what TaxCloud calculates, the merchant is still responsible for paying the taxes owed as determined by TaxCloud

Verifying Taxability Post-Upload

After uploading the order:

  • Retrieve the order via the Get Orders endpoint or view it in the dashboard.
  • Confirm that each line item reflects the correct TIC and tax values.
  • Ensure that exemptions are accurately recorded and appear in reporting tools.

TaxCloud does not recalculate tax on uploaded orders post-submission. If you find an error, you’ll need to delete and re-upload the order with corrections.

Conclusion

Handling taxability in uploaded orders requires more manual input than in real-time calculated orders, but it gives you control. Always:

  • Assign the correct tic to each item
  • Only use accurate tax values.
  • Properly configure exemptions for each customer or transaction.

Doing so ensures accurate compliance, reduces filing errors, and keeps your order data aligned with tax rules across jurisdictions.

Next Steps

If you have tax-exempt customers or transactions, continue to the Handle Exemptions for Uploaded Orders section.