CLARIFY: BILL sales tax defaults to Zero

Dev guide on sales tax says

Expenses, Bills and Bill items

Normally there is no need to specify the sales_tax_rate or the manual_sales_tax_amount for an expense, bill or bill item yourself. If you leave both of these fields out, the correct sales_tax_rate will be set for the category of the expense or bill.

However, we’re finding, with the “new” BILL endpoint, if neither 'sales_tax_rate" nor ‘manual_sales_tax_amount’ are specified, then ZERO sales tax is applied, not the rate/value appropriate for the item’s category. This behaviour is similiar to how Invoices work now.

Is this intentional (suggesting the Sales Tax info page needs an update too)? Or we might be doing it wrong… :-/


This can happen if the bill date is outside of a tax registration window or the tax isn’t reclaimable, as in both cases the sales tax has no accounting effect of its own.

I’m going to assume you’re using a “Universal” company rather than a UK company with VAT registration, but please correct me if that’s not the case. Under Settings, Sales Tax, you can configure sales tax registration periods:

In this example, if I created a bill dated before 01 Sep 2021, no sales tax would be added automatically to the bill item because it’s outside of a sales tax registration period.

There’s also a setting within the sales tax registration to say whether it’s reclaimable tax:


If this isn’t checked, then there’s no need to calculate or record the sales tax amount on the bill either as it has no effect. Hope that helps.


Thanks Dominic.

That’s interesting, and educational, but doesn’t fit out case. We found this anomaly (compared to how BILLs used to work in the deprecated API) with a UK VAT-registered company, with BILLs inside a sales tax registration period.


Hi Greg,

OK, that’s unexpected and I haven’t seen that in my testing on a UK company. Usually we would always record sales tax for their bills as the VAT may be reclaimable.

Could you double check that the category ID is specified correctly within bill_items, and that it’s definitely a VAT-applicable category?

Do you have an example create/update bill request please? Or better, the X-Request-ID header from the API response.

Kind regards,

Hi Dominic,
Sorry for the delay, we’ve had fixes to Fabio tested & rejected on this topic. I’ve subsequently become an expert with Google’s OAuth 2.0 Playground to explore how the new BILL endpoint behaves… (I’m not the dev, so that was fun) :smiley:

What it seems to boil down to is over-zealous value checking on a BILL’s manual_sales_tax_amount: In the new BILL endpoint, if “manual_sales_tax_amount” is POST with a null value (ie. “”), then FA API rejects it with the message “manual_sales_tax_amount is not a number”. But, the API does not reject any other optional parameter POST with a null “” value. It simply accepts it as unspecified.

This is new and different behaviour compared to the deprecated BILL endpoint, and all other optional FA fields. Historically, Fabio defaulted optional fields, with no value supplied (by the user), to null “”. This has worked well, for nearly 6 years :wink: eg. FA API does not complain if “sales_tax_rate” is supplied as null “”. It’s just this particular manual_sales_tax_amount field, in the new BILL endpoint, that seems to be behaving differently to everything else. This is nothing to do with Fabio, it has been confirmed with the OAuth playground.

Can FA revert the new BILL endpoint manual_sales_tax_amount value checking back to it’s less vigilant behaviour (ie. Allow “” as a valid value)? Given we were the first (and only?) team to find this field missing from the new BILL endpoint, I suspect reversion is not going to affect anyone else.

Thanks. Looking forward to your feedback…

Hi Greg,

I’ve re-tested the behaviour of the API prior to the introduction of bill items and it seems to return the same error of manual_sales_tax_amount is not a number when supplying "manual_sales_tax_amount": "" in a JSON request.

I haven’t been able to find any logs of these API calls either, unless it’s a particular combination of request parameters or company setup that I’m missing. The old request I tested with looks like this:

    "bill": {
        "contact": "{{url}}/contacts/4",
        "reference": "ManualVAT01",
        "dated_on": "2021-02-15",
        "due_on": "2021-02-20",
        "total_value": "123",
        "manual_sales_tax_amount": "",
        "description": "Test",
        "category": "{{url}}/categories/280"

Perhaps there’s something in the client filtering out empty values from the top-level request body before sending it, but doesn’t operate on nested objects?

If you have a sample request that worked before that doesn’t work now when converted to add bill_items, then that would be very helpful. I appreciate that it isn’t possible for you to test the old API now as we’re past the transition period.

Kind regards,

Thanks for your feedback. Obs, we couldn’t retest against the old API, nor do I still have any JSON that once worked (only PHP at a much higher level). We haven’t ever filtered-out empty “” values - we just crafted the code to do so, selectively against nominated attributes (so as not to break other stuff that already works). A BILL’s “manual_sales_tax_amount” is the first attribute to get this feature. And, status quo is restored. Users are happy again.