In this API: https://docs.clover.com/reference/createcharge
We send the amount as all inclusive of tax as described in the API and tax_amount separately. But in reports it seems like that amount along is treated of exclusive of tax_amount. Is this expected? if so how can we correct our api call so reports are balanced.
Pictures are attached for moderators due to being live account.
It looks like this may be an issue on our end, we will investigate.
The issue is that you are passing an arbitrary tax_amount that does not correspond with an existing tax rate set by the merchant. The tax_amount you pass has to be consistent with an existing tax rate or we cannot properly generate reports.
In this case the tax_amount did correspond to a tax_rate set by the merchant. That aside, having a "tax_amount equal to tax_rate" makes it a very hard requirement. Why is this needed to match at all?
Let's assume tax_amount did not match, so why would it be treated as "unpaid" balance. Obviously the charge did collect that amount. So our original question still remains unanswered: We send the amount as all inclusive of tax as described in the API and tax_amount separately. But in reports it seems like that amount along is treated of exclusive of tax_amount. Is this expected?
The tax_amount does not match for the order you provided. Information on calculating totals/taxes can be found here - https://docs.clover.com/docs/calculating-order-totals..
"Why is this needed to match at all?"
Taxes are very complex. I assume the reason you are providing a tax_amount is that you want the tax to be reported in Clover so that the merchant can pay the proper authority the proper amount when the taxes are due, correct? In order to do that the merchant needs to identify the name of the authority to pay. You have provided us a tax_amount with no context on what the tax is, what it is for, etc. We check the tax_amount you passed against the tax_rates the merchant has configured (which provides the context) and use the matching rate, in this case no match was found. The API should have rejected the request at this point, but it did not, we are looking into this. So, what are our options in this case? Dynamically creating a tax rate is problematic because if you have passed an invalid amount (as you did here) we have know way to properly name the tax (California State Sales Tax, etc.) because we have no context. The best we could do is create a tax rate with a % as a name which at the end of the day may be an invalid rate for the merchant (because we are relying on you to properly set it) and the merchant will have no idea what it is or whom to pay.
In the short-term I am guessing our API will change to reject requests where a tax_amount is passed that does not match any of the merchant's configured tax rates. In the long-term we are trying to make this easier for developers, it is just complicated and is going to take some time.
General note on API: Ecommerce charge API did not have fields for tax authority. How can we provide something there? Rejecting when amount does not match a rate is problematic as it breaks the API for all who are using it.
Also, Ecommerce API isn't the only one allowing amount. You have v3 orders line_items allows custom rate or custom flat rate with no context of tax authority. Will those be rejected as well?
I think the way it is today just fine, just don't try to match rates and fix the reports. Clover does not need to enforce tax correctness (unless you want to offer a competing Tax API like Avalara). In our experience, if app does something wrong with amounts, merchants discover it within a day or a week.
"General note on API: Ecommerce charge API did not have fields for tax authority. How can we provide something there? Rejecting when amount does not match a rate is problematic as it breaks the API for all who are using it."
There is a tax_uuid property on the request. You will need to 1) Either pass the id of an existing tax rate as tax_uuid or 2) Calculate the tax_amount so that it matches an existing tax rate. If you don't do 1 or 2 we cannot properly generate the reports.
"Also, Ecommerce API isn't the only one allowing amount. You have v3 orders line_items allows custom rate or custom flat rate with no context of tax authority. Will those be rejected as well?"
Our order endpoints require (when non Clover inventory is being used) an array of existing tax rates to be passed if any tax is going to be recorded on the order.
"I think the way it is today just fine, just don't try to match rates and fix the reports. Clover does not need to enforce tax correctness (unless you want to offer a competing Tax API like Avalara). In our experience, if app does something wrong with amounts, merchants discover it within a day or a week."
Please see my recommendation above.
My point was none of this behavior was documented in API.
>>2) Calculate the tax_amount so that it matches an existing tax rate.
This does not make sense. Look at this documentation at API: "Amount paid in taxes. This value is not automatically added to the total amount, so apps must ensure the value of the amount property is the correct final charge."
This documented behavior is exactly what we want: "Amount Paid in taxes". There should not be any additional matching to rate. What you are really looking for is which tax authority should this amount be attributed to. That is not Tax Rate. There needs to be a tax authority UUID of sorts.
Also what about the case when Merchant has not setup taxes on Clover? Will amount be allowed and reported correctly then?
I understand you are asking us to match the rate, for now. But keep that aside, the sales report is not making sense. It says "Collected Taxes" = $6.25 and "Unpaid Balance" = $6.25. If taxes were "collected" (which indeed they were because amount of charge included the tax as per API) how can it be "Unpaid"?
Edit: I just realized, even if we were to implement tax_uuid field, it would not fully work the way you are intending because its a single field and not an array. In most of US where there are multiple taxes for Products & services at minimum, ecommerce API will not work. So you have to make it an array of taxes, at which point, we might as well use v3/order based charges.
As I said, this is complex. We can argue about this all day long but the system currently works a certain way and that can't be quickly or easily changed. How taxes currently work in our system is that tax rates MUST be defined and any payments/orders must reference the existing tax rates for reporting etc. to be accurate. This largely stems from our roots as a card-present solution in a fixed locale. I agree that the documentation around tax_amount does not explain this.
I understand this is not ideal for you, and we are trying to figure out something that will be, but until then you need to either 1) Pass a tax_uuid or 2) Pass a tax_amount that corresponds to an existing tax rate set by the merchant (or via API).
1 Person is following this question.
