question

kirank avatar image
kirank asked kirank commented

Tax sent in Ecommerce Charge API seems to be not reported correctly

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.

e-commerce apiTaxes
10 |2000 characters needed characters left characters exceeded

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

David Marginian avatar image
David Marginian answered David Marginian commented

It looks like this may be an issue on our end, we will investigate.

2 comments
10 |2000 characters needed characters left characters exceeded

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

Any updated on this?
0 Likes 0 ·
No, I created a ticket and the team has acknowledged it bit it hasn't been investigated yet.
0 Likes 0 ·
David Marginian avatar image
David Marginian answered David Marginian edited

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.

10 |2000 characters needed characters left characters exceeded

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

kirank avatar image
kirank answered kirank commented

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?

2 comments
10 |2000 characters needed characters left characters exceeded

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

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.

0 Likes 0 ·
kirank avatar image kirank David Marginian ♦♦ ·

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.


0 Likes 0 ·
David Marginian avatar image
David Marginian answered kirank edited

"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.

1 comment
10 |2000 characters needed characters left characters exceeded

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

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.

0 Likes 0 ·
David Marginian avatar image
David Marginian answered kirank commented

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 comment
10 |2000 characters needed characters left characters exceeded

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

I'm trying to separate argument from technical behavior questions :) . Thanks for following up for a solution. We'll do more experimenting with UUID and matching amounts
0 Likes 0 ·

Write an Answer

Hint: Notify or tag a user in this post by typing @username.

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

Welcome to the
Clover Developer Community