question

jms avatar image
jms asked ·

Delivery Charges for Orders on REST API

Hi. We want to add a flat delivery charge for an order over the REST API. We did the following suggestions to support this:

https://community.clover.com/questions/11286/how-to-apply-delivery-fees-to-delivery-orders.html

However, now we face a different issue. In the scenario where order level amount discount is present, this discount gets divided across all line items which now include the delivery charge line item as well. This in turn causes the tax calculation of the line items with applicable taxes to change since tax is applied on the item price after discounts.

For example, let's say we have 4 line items with taxes and a delivery charge which we also add as a line item. Also lets say we have an amount discount as $20. A correct calculation will allocate the discount across the 4 items and charge tax on the price after discount for each of them.

However, by adding delivery charge as a line item, the same discount amount is now allocated across 5 items, resulting in lower discount allocation per item leading to higher item price after discount resulting in higher tax charged (even though the delivery charge line item has no assigned taxes).

The real problem occurs when we use the values calculated in the former scenario in a clover e-commerce payment. Even though we charge the proper total, the order shows up as partially paid since clover internally recalculates and arrives at some totals that reflect the latter scenario. We could make the same calculation error in our side so that the values match, but this would mean we are charging a wrong tax amount from our customers.

Is there a way to create a line item over the REST API with a price that should be discount excluded and tax excluded?

Or is there a better way to add a flat charge for an order so we can call it a delivery charge? (other than service charge. We already use that to capture service charges)

The following response https://community.clover.com/questions/14159/custom-line-items-for-delivery-charge.html on 2018 says that this is not possible and I would like to know if any developments have been done in this area to support this scenario since then.

Thank you

OrdersREST APITaxesDiscounts
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.

brokenoval avatar image
brokenoval answered ·

There's a hacky way around this that works most of the time if you don't require service charges elsewhere and don't mind making a couple of queries. Imagine the following order:


itemA: $10

discount: : $1.50

deliveryCharge: $2

tax: 10%


First GET the `/default_service_charge` so you can fetah the $serviceChargeId


Then POST to `/orders/:orderId/service_charge` with:

{
"id": $serviceChargeId,
"name": "whateveryoulike",
"percentageDecimal": ( deliveryCharge/ (itemA - discount) ) * 1000000
}


This gets into difficulty with small orders or large discounts as the % service charge cannot be more than 100% of the post discount total. This approach ends up adding a non revenue charge that doesn't affect tax or discounts which is pretty useful and (I believe) the proper way of handling a delivery fee.


NB: my multiplier might be slightly off, basically trying to get 23.5294% of 8.5 which equals the required deliveryCharge of $2.

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.

vikram avatar image
vikram answered ·

I know that this is convoluted but we are thinking to implement this as below.

Number of Items	Description	             Rate
1	              Item A @10.99	    10.99
2	              Item B @6.78	    13.56
1	              Item C @10.00	    10.00
 	                           Discount -5.00
 	                           Delivery  3.00
                                     Total  32.55
 	                           Tax 6%    1.95
 	                        Sub Total   34.50
                                      Tip    2.50
 	                      Grand Total   37.00

The first item is 10.99, the second is 6.78 and the third is 10. The discount is 5 on all items but not on delivery and tip. The tax is 6%. The subtotal is 34.50 and tip without tax is 2.5 and the grand total is 37.00

Now, as clover does the tax on each line item, doing a discount is problematic as it will apply to the delivery as well and we can not have a discount on delivery.

A possible solution to the above is:

Calculate the total number of items - which is 4 in our case (do not include line-item delivery). Then, calculate the discount per item - which is 1.25 in our case (5/4). Now, subtract 1.25 from first, 2.5 from second, and 1.25 from 3rd line items.

Delivery is taxable in most states and we will include this as a line item.

The modified table will look like.

Number of Items	Description	                Rate
1	              Item A @9.74 (Orig 10.99)	 9.74
2	              Item B @5.53 (Orig 6.78)	11.06
1	              Item C @8.75 (Orig 10.00)	 8.75
 	                            Delivery	   3.00
 	                                 Total	32.55
 	                                  Tax 6%	1.95
 	                                   Tip	2.50
 	                           Grand Total	37.00


In this case, the total will not change and we will still have delivery line items that will not get reduced due to the discount. The tip will not get taxed unless we specify it as Clover allows it to be taxed or not taxed.

Then, we should add a line somewhere in the receipt which will say that your saved 5 on this order due to a discount.

Now, the key here is to show the original and discounted price for each line item in the description to make it clear that we applied the discount on the price so that there is no confusion otherwise people will start a quarrel that where is the discount.

The right thing is for Clover to come up with a new API that does it correctly instead of the above-convoluted solution.

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 ·

Your description of how a fixed amount order level discount is applied seems inaccurate. The key to computing the total when you have an order level discount that is a flat fee is converting it into a percentage. That is done by taking the pre-tax subtotal and dividing the tax amount from it. Let's say we have an order with two 10$ items, one with a 10% tax rate and the other with a 5% tax rate. The pre-tax subtotal is 20 the tax is 1.50 (10*0.1 + 10*0.05) and the total is 21.50. Now if we add an order level discount of 2.00 the discount % is calculated as 2 / 20 (discount / pre-tax subtotal) or .1 (this is the same as a 10% discount). The subtotal is 20, the tax is 1.35 ($10*0.9*0.1 + $10*0.9*0.05, the .9 is 1 - the discount %). The total for this order would be 19.35 (20 - 2 + 1.35). If there was another item (1.50, delivery charge) the pretax subtotal would be 21.50, the new discount % would be .906976744 (1 - .093023256) and the tax would be 1.36 (round($10*0.906976744*0.1) + round($10*0.906976744*0.05) + round(1.50*0.906976744*0)) and the total would be 21.50 + 1.36 - 2 = 20.86.

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

Hi David. Thanks for the detailed answer. Here is why this won't work:

In the second scenario (with delivery charge 1.50), the pre-tax subtotal is 21.50 (like you said), but the discount multiplier now works out to 2/21.50 = 0.093...

This will in turn affect the taxes charged right? ($10*0.906*0.1 + $10*0.906*0.05 + 1.50*0.906*0) = $0.91 + $0.45 = $1.36 (a difference in $0.01)

This is what I mentioned here:

However, by adding delivery charge as a line item, the same discount amount is now allocated across 5 items, resulting in lower discount allocation per item leading to higher item price after discount resulting in higher tax charged (even though the delivery charge line item has no assigned taxes).

This happens because clover does not know that the delivery charge is a non-discount-applicable line item and we can't set the order total due to the reasons mentioned and end up being forced to go through clover internal bill calculation.

0 Likes 0 ·

Sorry, in my haste I failed to recompute the discount % for the delivery charge item in my example above, I have fixed that. So that I am clear on your position, you feel that the total tax charged should be 1.35 here (the discount % should be 2/20 or .1), instead of the Clover computer 1.36?

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

Yes @David. Because the alternative is a bad one where we have to overcharge our customers just to avoid partially paid issues. It's only 1cent here but this accumulates with no. of line items, no. of taxes applied, etc...

0 Likes 0 ·
Show more comments
David Marginian avatar image
David Marginian answered ·
The real problem occurs when we use the values calculated in the former scenario in a clover e-commerce payment. Even though we charge the proper total, the order shows up as partially paid since clover internally recalculates and arrives at some totals that reflect the latter scenario.

Can you expand on this? What APIs are you using? The order/pay endpoint shouldn't be calculating totals unless you haven't set a total on the order.

Can you provide an example order and what you believe the total should be?

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

Hi @David. We use the following endpoints https://api.clover.com/v3/merchants/{merchantId}/orders (order placement), https://scl.clover.com/v1/orders/{orderId}/pay (tokenized charge).

We have been suggested this workaround before in situations like https://community.clover.com/questions/24312/overcharging-on-ecommerce-api-if-order-has-discoun.html?childToView=25186#comment-25186.

However, we can't follow this suggestion to set total before ecommerce payment for the same reason, which basically is if the order total is set before payment, the order shows up in the Clover Orders App. If the customer doesn't go through with the payment, this would mean there is an incomplete order in the Orders App that merchant will now start to prepare.

Is the above scenario rectified since then? Can we now place orders over the API along with totals BUT prevent them from being seen in the Orders App? If so please let us know.

If not, what can be done for the OP question?

Is there a way to create a line item over the REST API with a price that should be discount excluded and tax excluded?
Or is there a better way to add a flat charge for an order so we can call it a delivery charge? (other than service charge. We already use that to capture service charges)

0 Likes 0 ·
Is there a way to create a line item over the REST API with a price that should be discount excluded and tax excluded?

I don't believe so.

Or is there a better way to add a flat charge for an order so we can call it a delivery charge? (other than service charge. We already use that to capture service charges)

I have to ping some folks and do some more research on this. I will get back to you when I have something concrete to share.

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

Thank you @David Marginian we are eagerly waiting for a solution.

1 Like 1 ·
Show more comments

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