Skip to main content
Some billing systems record collected sales tax as a line item, for example a “Sales Tax” item on an invoice, instead of in the transaction’s tax field. Mark such a line with the SALES_TAX product tax code and Taxwire treats its amount as tax collected, not as something sold.

​
What happens to the line

Transactions. When you create or update a transaction, Taxwire removes every SALES_TAX line from line_items and adds its amount (unit_price × quantity) to the transaction’s tax_amount. The line is never taxed and never counts toward the taxable base, gross sales or economic nexus thresholds. The response shows the remaining line items and the combined tax_amount. It does not return the removed lines, so keep your own copy if you need to send them again. Any SALES_TAX line, even one of 0, gives the transaction a provided tax: filing_tax_amount is the combined tax_amount with filing_tax_amount_source: "provided", not the tax Taxwire calculates. Transaction-level discounts apply to the remaining line items only. Calculations. POST /calculations accepts the line and leaves it out of the taxable base. The response lists it by id with a tax_amount of 0, and the calculation’s total tax_amount does not include it. A calculation has no provided tax to add the line to, so sum your SALES_TAX lines yourself if you need the total collected.

​
Send the tax in one place

The tax field and SALES_TAX lines are added together. If tax_amount already includes the tax on a SALES_TAX line, don’t also send the line: Taxwire adds both, and your returns report the sum as tax collected.

​
Rules

A SALES_TAX line must:
  • carry SALES_TAX as its only tax attribute: no other code beside it (["SALES_TAX", "TANGIBLE_PERSONAL_PROPERTY"]) and no attribute suffix (SALES_TAX._B2B)
  • have no discount: no non-zero discounts, discount_amount or vendor_discount_amount; send the tax actually collected
  • have a non-negative amount; for a refund, use a credit transaction with positive amounts, as with any other line. If your system records a correction as a second, negative tax line, net the tax lines into one before sending.
  • have an id no other line in the transaction uses
The code is case-sensitive: sales_tax is not recognised. A line that breaks a rule is refused with HTTP 422 and the error code validation_error:
  • On transactions, detail names the line and the rule, for example line item 'tax_line': a SALES_TAX line cannot carry a discount.
  • On POST /calculations, detail is Validation failed: invalid_sales_tax_line, or Validation failed: multiple errors if the request has other validation errors too (Processing failed: multiple errors if one of them is a calculation error). It does not name the line.

​
Marking a product

If your line items reference products through presets, you can mark the product instead of each line. In the Taxwire App, open the product on the Products page and choose Collected sales tax (SALES_TAX) as its only tax code. It is not offered in bulk assign and can’t be your default tax code. Every line that references the product through its preset is then treated as a SALES_TAX line, on transactions and on calculations. Tax attributes sent on the line itself take precedence over the product’s. A marked product’s line may carry discounts: Taxwire uses the line’s amount less its own discounts, rounded to the smallest currency unit. The other rules apply as above. If that amount is negative:
  • on transactions, the line is refused with HTTP 422, like a line you declared yourself;
  • on POST /calculations, the line is left out of the calculation and returned with a tax_amount of 0, and the request does not fail.
On QuickBooks, NetSuite and Stripe invoices, a negative marked line is netted with the document’s other marked lines instead. A net of 0 or more is kept as one line. A negative net lowers the document’s tax, never below 0, and leaves its goods lines unchanged. A sale, or a credit with no parent, whose only lines are marked lines netting below 0 is not recorded on NetSuite or Stripe; on QuickBooks it is stored with no line items and its tax stays off returns. Stripe credit notes are not netted.

​
When a mark takes effect

  • Marking or un-marking a product changes how Taxwire records the transactions it receives after the change.
  • Transactions Taxwire already stored are not converted until the source sends them again: any re-sync for Stripe and NetSuite, a newer version of the order for Shopify, the document again for QuickBooks. For a transaction you created through the API, that means sending its line_items again (see Updating a transaction). If a stored transaction is recalculated before then, the marked line is left out of its sales but not added to its collected tax.
  • QuickBooks lines keep the tax code they arrived with, so a QuickBooks transaction stored before the mark keeps the line as a taxed sale, on recalculation and in nexus studies, until QuickBooks sends it again.
  • Un-marking a product does not turn transactions already recorded as collected tax back into sales until the source sends them again.
  • Nexus studies apply the product’s current mark to the line items of stored transactions from the next study. Un-marking counts a line as a sale again only on transactions that still list it; lines already recorded as collected tax stay out of nexus until the source sends the transaction again.

​
Updating a transaction

  • Sending line_items (draft transactions only): send the full list again, including the SALES_TAX lines. The tax amount is recomputed from these lines plus the tax_amount you send, or the one you sent before if you omit it. A SALES_TAX line you leave out is removed from the tax amount. If no SALES_TAX line and no tax_amount are left, the transaction has no provided tax and Taxwire uses the tax it calculates.
  • Sending only tax_amount: it replaces the tax_amount you sent before. SALES_TAX lines already counted in the tax amount stay counted.
The tax_amount in a transaction response already includes the SALES_TAX lines. Don’t send it back as tax_amount on an update, or those lines are added again. Send only the tax you collected outside the lines.
To change the line items of a finalized transaction, set its status to draft, then send line_items with status: finalized in a second call. A filed transaction’s line items can’t be changed.

​
Tax-only transactions

A sale, or a credit sent without parent_transaction_id or parent_reference_id, whose only line items are SALES_TAX lines is stored with no line items. Taxwire reports its tax on your returns in the jurisdictions of the customer address on the SALES_TAX lines, with gross and taxable sales of 0. The tax is split equally across the jurisdictions that address reaches where you are registered. Lines at several addresses share the total equally across the jurisdictions they reach where you are registered, whatever each line held. If you are registered in none of them, the tax is on no return. Every SALES_TAX line on a tax-only transaction needs a customer address. Without one, Taxwire stores the transaction but holds it off returns. A tax-only credit that names a parent transaction is not reported yet; see Limitations.

​
Examples

Amounts are in the smallest currency unit, so 635 is $6.35. The “Tax in both places” example leaves customer addresses out.

​
Limitations

  • A credit without line items does not reverse SALES_TAX lines. A credit with a parent_transaction_id and no line_items copies the parent’s stored line items, which no longer include its SALES_TAX lines. Its tax is calculated on those line items, so it reverses the tax Taxwire calculates on them, not the tax the parent carried in tax_amount or as SALES_TAX lines. To reverse all of it, send the credit’s tax_amount yourself, or send the same line_items and tax_amount you sent on the sale. A tax-only sale can’t be reversed this way: its stored line items are empty, so the credit copies nothing and stays off returns. If you marked a product after the sale was calculated, the copied line on that product is left out of the credit, so the credit does not reverse the tax the sale calculated on it.
  • A tax-only credit that names a parent is not reported yet. Taxwire stores a credit whose only line items are SALES_TAX lines and that has a parent_transaction_id or parent_reference_id, even one that never matches a transaction, but holds it off returns.