TaxJar API: How to address bad math
The release of Version V2 - 2020 of the TaxJar API (dated 2020-08-07) includes mathematical validation of API calls.
In this version of the API, requests to the TaxJar API /v2/transactions endpoint that include bad math will return the following:
{
"status": 400,
"error": "Bad Request",
"detail": "amount must be equal to the sum of line items and shipping, excluding sales tax."
}
A 400 error, like the one above, means that the transaction will not be created in TaxJar due to arithmetical discrepancies between the request body level ‘amount’ and ‘line_items’ details. Please note, when transactions fail to be created, they will not be available in your list of transactions or your state reports in TaxJar. Therefore, you will need to ensure you have the ability to review failed transaction API calls to TaxJar.
Why are there API failures or discrepancies?
The reasons for transactions resulting in discrepancies or failures can vary and depend on how your software interacts with constructing transaction API calls. For this reason, it is difficult to advise on what precisely must be corrected. However, the most common causes are when the sum of ‘line_items’ does not match the subtotal in the ‘amount’.
What is an example of an API failure and how do I fix it?
In the below refund example, note that the sum of ‘line_items’ + ‘shipping’ does not equal the ‘amount’:
# POST /v2/transactions/orders
{
"transaction_id": "refund-0001",
"transaction_date": "2021-01-07",
"from_street": "9663 Santa Monica Blvd",
"from_city": "Beverly Hills",
"from_zip": "90210-4705",
"from_state": "CA",
"from_country": "US",
"to_street": "9663 Santa Monica Blvd",
"to_city": "Beverly Hills",
"to_zip": "90210-4705",
"to_state": "CA",
"to_country": "US",
"line_items": [{
"product_tax_code": "",
"product_identifier": "FW-01",
"sales_tax": -0.48,
"quantity": 1,
“Discount”: 0,
"description": "Fuzzy Widget 01",
"unit_price": -5.00
}, {
"product_tax_code": "",
"product_identifier": "MW-01",
"sales_tax": -0.48,
"quantity": 1,
“Discount”: 0,
"description": "Metal Widget 01",
"unit_price": -5.00
}
],
"sales_tax": -0.96,
"shipping": -10,
"amount": -15.00
}
The true ‘amount’ should equal -20.00. This works out from the following:
-5.00 (first line_item)
+ -5.00 (second line_item)
+ -10.00 (shipping)
= -20.00 (amount)
Please note, the reasons for why the request body could be built incorrectly may depend.
Developers should review the following:
1) Identify what methods and code define
‘line_items[*].quantity’‘line_items[*].discount’‘line_items[*].unit_price’‘line_items[*].sales_Tax’‘amount’
2) Ensure ‘line_items[*]’ iteration is always quantity * unit_price - discount = line_item total
3) Ensure ‘amount’ is always line_item total + shipping
4) Ensure 'sales_tax’ is always the sum of all ‘line_items[*].sales_tax’