Calculating tax on a discounted lineitem

Question

question

brandin asked Feb 11, '21 brandin commented Mar 22, '21

Calculating tax on a discounted lineitem

We're working with the Clover REST API, and am seeing an odd behaviour with the calculated tax of lineitems that have been discounted.

We're making the following assumptions based on what we see from the API:
* tax RATE information is provided at the lineitem level

* tax AMOUNT information is provided at the order level

What we're seeing is this:

If we add an item to the order, say 5.00, that has a linked taxRate of 0.10, the lineitem total should be calculated to 5.50.

If we look at this order, we see a taxRate that matches this in the API.

The problem arrises when we try to apply a discount to this item. If we add a 100% discount, the lineitem price should now be interpreted as 0.00. This is fine, as when we try to calculate a tax amount ourselves, 0.10 * 0 === 0.00.

However, we've noticed that the taxRate at the order level remains at 0.50. This number appears to be calculated by Clover, and the order API doesn't allow us to edit this manually.

So we end up with an order total of 0.00, but with a taxAmount of 0.50, which clearly doesn't make sense.

How is this meant to be handled?

For reference, I've attached a sample order:

{
   "href":"<REDACTED>",
   "id":"91SWPYNMKPAWG",
   "currency":"USD",
   "employee":{
      "id":"9Z1RS40CEDN7G"
   },
   "total":0,
   "paymentState":"PAID",
   "title":"brandin Chiu",
   "taxRemoved":false,
   "isVat":false,
   "state":"locked",
   "manualTransaction":false,
   "groupLineItems":true,
   "testMode":false,
   "createdTime":1613058954000,
   "clientCreatedTime":1613058954000,
   "modifiedTime":1613058962000,
   "lineItems":{
      "elements":[
         {
            "id":"RD418EJG33YE6",
            "orderRef":{
               "id":"91SWPYNMKPAWG"
            },
            "item":{
               "id":"5DXWAPFW7A3CE",
               "hidden":false,
               "name":"2 Ladies*",
               "code":"G01014",
               "price":413,
               "priceType":"FIXED",
               "defaultTaxRates":true,
               "unitName":"",
               "cost":0,
               "isRevenue":true,
               "stockCount":0,
               "modifiedTime":1605675865000
            },
            "name":"2 Ladies*",
            "price":413,
            "itemCode":"G01014",
            "note":"Shaken, not stirred",
            "printed":false,
            "createdTime":1613058955000,
            "orderClientCreatedTime":1613058954000,
            "discounts":{
               "elements":[
                  {
                     "id":"MQQWAD29XT7BR",
                     "orderRef":{
                        "id":"91SWPYNMKPAWG"
                     },
                     "lineItemRef":{
                        "id":"RD418EJG33YE6"
                     },
                     "name":"free",
                     "percentage":100
                  }
               ]
            },
            "exchanged":false,
            "modifications":{
               "elements":[
                  {
                     "id":"C3ATY0STAN2JJ",
                     "lineItemRef":{
                        "id":"RD418EJG33YE6"
                     },
                     "name":"( M )",
                     "amount":0,
                     "modifier":{
                        "id":"EN0CJHZC0ZKPA"
                     }
                  },
                  {
                     "id":"V60Q2Z3F54ANM",
                     "lineItemRef":{
                        "id":"RD418EJG33YE6"
                     },
                     "name":"+Tapioca",
                     "amount":69,
                     "modifier":{
                        "id":"1N7932SM1QGCW"
                     }
                  },
                  {
                     "id":"GP3NKR6GT6XEG",
                     "lineItemRef":{
                        "id":"RD418EJG33YE6"
                     },
                     "name":"+Aloe Vera",
                     "amount":69,
                     "modifier":{
                        "id":"1E5ZWY5FCBQHE"
                     }
                  },
                  {
                     "id":"ZHY296RVTK1AC",
                     "lineItemRef":{
                        "id":"RD418EJG33YE6"
                     },
                     "name":"(Sweeter)",
                     "amount":0,
                     "modifier":{
                        "id":"SQ817E71DXT0E"
                     }
                  },
                  {
                     "id":"G12JJRDVJ6EHY",
                     "lineItemRef":{
                        "id":"RD418EJG33YE6"
                     },
                     "name":"(Regular Ice)",
                     "amount":0,
                     "modifier":{
                        "id":"5968E2V61DSQ2"
                     }
                  }
               ]
            },
            "refunded":false,
            "isRevenue":true,
            "taxRates":{
               "elements":[
                  {
                     "id":"VBXP2R1MCD2YP",
                     "lineItemRef":{
                        "id":"RD418EJG33YE6"
                     },
                     "name":"NY Sales Tax",
                     "rate":887500,
                     "isDefault":true
                  }
               ]
            }
         }
      ]
   },
   "taxRates":{
      "elements":[
         {
            "id":"VBXP2R1MCD2YP",
            "name":"NY Sales Tax",
            "amount":48
         }
      ]
   }
}

EDIT: We tested again using two drinks, and the correct taxAmount on the payment, but did the order still has the wrong taxAmount on it:

{
    "href": "<REDACTED>",
    "id": "CJ0EQZKMJGW8A",
    "currency": "USD",
    "employee": {
        "id": "9Z1RS40CEDN7G"
    },
    "total": 475,
    "paymentState": "PAID",
    "title": "brandin chiu",
    "taxRemoved": false,
    "isVat": false,
    "state": "locked",
    "manualTransaction": false,
    "groupLineItems": true,
    "testMode": false,
    "createdTime": 1616115883000,
    "clientCreatedTime": 1616115883000,
    "modifiedTime": 1616115886000,
    "lineItems": {
        "elements": [{
                "id": "5MK7620A765PP",
                "orderRef": {
                    "id": "CJ0EQZKMJGW8A"
                },
                "item": {
                    "id": "P16DGQX38D03T",
                    "hidden": false,
                    "name": "2 Ladies",
                    "alternateName": "",
                    "code": "G01014",
                    "sku": "MT000100B2",
                    "price": 436,
                    "priceType": "FIXED",
                    "defaultTaxRates": true,
                    "unitName": "",
                    "cost": 3,
                    "isRevenue": true,
                    "stockCount": 0,
                    "modifiedTime": 1612216810000
                },
                "name": "2 Ladies",
                "alternateName": "",
                "price": 436,
                "itemCode": "G01014",
                "note": "",
                "printed": false,
                "createdTime": 1616115883000,
                "orderClientCreatedTime": 1616115883000,
                "discounts": {
                    "elements": [{
                        "id": "5H8D4D2H4ZDM4",
                        "orderRef": {
                            "id": "CJ0EQZKMJGW8A"
                        },
                        "lineItemRef": {
                            "id": "5MK7620A765PP"
                        },
                        "name": "BOGO_Launch Event",
                        "percentage": 100
                    }]
                },
                "exchanged": false,
                "modifications": {
                    "elements": [{
                            "id": "BCH78FYW7VNA8",
                            "lineItemRef": {
                                "id": "5MK7620A765PP"
                            },
                            "name": "( M )",
                            "amount": 0,
                            "modifier": {
                                "id": "ZN7QD4BP4F73J"
                            }
                        },
                        {
                            "id": "BZZ3TZ3JFP08T",
                            "lineItemRef": {
                                "id": "5MK7620A765PP"
                            },
                            "name": "(Regular Ice)",
                            "amount": 0,
                            "modifier": {
                                "id": "ARHY5QR86TXV4"
                            }
                        },
                        {
                            "id": "BFJQ6RHKJJ6G6",
                            "lineItemRef": {
                                "id": "5MK7620A765PP"
                            },
                            "name": "(Sweeter)",
                            "amount": 0,
                            "modifier": {
                                "id": "CY7DBTFJT6MPA"
                            }
                        },
                        {
                            "id": "6FXNAKS5RFB2P",
                            "lineItemRef": {
                                "id": "5MK7620A765PP"
                            },
                            "name": "Regular",
                            "amount": 0,
                            "modifier": {
                                "id": "WGCT8XY76J63A"
                            }
                        }
                    ]
                },
                "refunded": false,
                "isRevenue": true,
                "taxRates": {
                    "elements": [{
                        "id": "K39PGKDKFYD2C",
                        "lineItemRef": {
                            "id": "5MK7620A765PP"
                        },
                        "name": "NY Sales Tax",
                        "rate": 887500,
                        "isDefault": true
                    }]
                }
            },
            {
                "id": "QWEG1P1NWXGC6",
                "orderRef": {
                    "id": "CJ0EQZKMJGW8A"
                },
                "item": {
                    "id": "P16DGQX38D03T",
                    "hidden": false,
                    "name": "2 Ladies",
                    "alternateName": "",
                    "code": "G01014",
                    "sku": "MT000100B2",
                    "price": 436,
                    "priceType": "FIXED",
                    "defaultTaxRates": true,
                    "unitName": "",
                    "cost": 3,
                    "isRevenue": true,
                    "stockCount": 0,
                    "modifiedTime": 1612216810000
                },
                "name": "2 Ladies",
                "alternateName": "",
                "price": 436,
                "itemCode": "G01014",
                "note": "",
                "printed": false,
                "createdTime": 1616115884000,
                "orderClientCreatedTime": 1616115883000,
                "exchanged": false,
                "modifications": {
                    "elements": [{
                            "id": "F3T840QG8FK9M",
                            "lineItemRef": {
                                "id": "QWEG1P1NWXGC6"
                            },
                            "name": "( M )",
                            "amount": 0,
                            "modifier": {
                                "id": "ZN7QD4BP4F73J"
                            }
                        },
                        {
                            "id": "S464M2MR0FXQJ",
                            "lineItemRef": {
                                "id": "QWEG1P1NWXGC6"
                            },
                            "name": "(Regular Ice)",
                            "amount": 0,
                            "modifier": {
                                "id": "ARHY5QR86TXV4"
                            }
                        },
                        {
                            "id": "SFYJDC17A629R",
                            "lineItemRef": {
                                "id": "QWEG1P1NWXGC6"
                            },
                            "name": "(Sweeter)",
                            "amount": 0,
                            "modifier": {
                                "id": "CY7DBTFJT6MPA"
                            }
                        },
                        {
                            "id": "99PN88P0RPVS6",
                            "lineItemRef": {
                                "id": "QWEG1P1NWXGC6"
                            },
                            "name": "Regular",
                            "amount": 0,
                            "modifier": {
                                "id": "WGCT8XY76J63A"
                            }
                        }
                    ]
                },
                "refunded": false,
                "isRevenue": true,
                "taxRates": {
                    "elements": [{
                        "id": "K39PGKDKFYD2C",
                        "lineItemRef": {
                            "id": "QWEG1P1NWXGC6"
                        },
                        "name": "NY Sales Tax",
                        "rate": 887500,
                        "isDefault": true
                    }]
                }
            }
        ]
    },
    "taxRates": {
        "elements": [{
            "id": "K39PGKDKFYD2C",
            "name": "NY Sales Tax",
            "amount": 77
        }]
    },
    "payments": {
        "elements": [{
            "id": "F5GY30B3EHRCP",
            "order": {
                "id": "CJ0EQZKMJGW8A"
            },
            "tender": {
                "href": "<REDACTED>",
                "id": "9M4D54Z8MP7Q2"
            },
            "amount": 475,
            "tipAmount": 0,
            "taxAmount": 39,
            "employee": {
                "id": "9Z1RS40CEDN7G"
            },
            "createdTime": 1616115887000,
            "clientCreatedTime": 1616115887000,
            "modifiedTime": 1616115886000,
            "result": "SUCCESS",
            "note": "<REDACTED> QuickPay"
        }]
    }
}

Orders Taxes

10 |2000

Attachments: 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

Answer 1 · 2021-02-11T20:11:59Z

David Marginian Deactivated answered Feb 11, '21 brandin commented Mar 22, '21

Your app is creating a payment record for the order and you are passing in a tax of 48:

RequestLog{reqBody={"note":"redacted, your app name + QuickPay","amount":0,"tipAmount":0,"taxAmount":48,"tender":{"id":"redacted"}}

15

10 |2000

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

brandin commented · Mar 19, 2021 at 08:45 PM

hey David. We recently performed some additional tests and are still confused now by this explanation. We've recently modified how our payments end calculates taxes to ensure that it's only submitting taxes for portions that should be taxed.

However, if we perform the same test as above, but with two drinks, and one discounted, the taxAmount on the order incorrectly includes the taxable sum of BOTH drinks, even though one is discounted to zero, AND the subsequent payments correctly includes the halved taxAmount.

I've updated the question to include this second example.

0 ·

David Marginian ♦♦ brandin commented · Mar 19, 2021 at 09:11 PM

Have you went through our docs here - https://docs.clover.com/docs/calculating-order-totals.

If you have and you are still having issues, please provide me with the following:

1) How you are creating the order and calculating the total.

2) Provide me with an order id (and environment), and what you expect the total and tax to be and what the problem is (We set the total to X, and Clover shows it as X on the receipt, etc.)

0 ·

brandin David Marginian ♦♦ commented · Mar 19, 2021 at 09:52 PM

Yes, We've definitely read through those docs, and are using that formula to calculate the totals. The issue isn't that our tax calculations are wrong, but that Clover is seemingly coming up with it's own numbers somehow that we can't explain.

The only thing that our app does is allow cashiers to add special discounts to an order from the payments screen. So we will be given a "complete" order, with lineitems, modifiers, and any other included discounts.

In most cases, the order totals are already calculated for us by the time we get the order from the Register app.

After we receive the order, the cashier can optionally add any final discounts from our app. If they do, we recalculate the order total based on the required formula, and submit it to Clover using the following API

POST /merchants/x/orders/y
{
"total": <NEW_TOTAL>
}

At no point do we ever submit a taxAmount value to Clover (and don't even see a way to do this from the reference docs). What appears to be happening is that Clover has already set the order taxAmount based on the order state BEFORE it gets to our app. But after we apply additional discounts and modify the order total, that taxAmount is never updated, and we can't do it ourselves.

In the above example, all of the numbers are correct, EXCEPT for the order.taxRates[0].amount value, which is the calculated tax of both lineitems. However, one of those lineitems was discounted to 0.00, so that value should be halved, and be closer to the taxAmount we calculate as part of the payment object.

That is what we're expecting.

0 ·

Show more comments

question