Freeside:4:Documentation:Administration:Tax Districts
Contents
Overview
Freeside supports billing taxes by district, instead of city/county/state.
Currently this is only supported in the state of Washington. Public data sources provided by the Washington Dept. of Revenue are used to automatically maintain tax rate tables, and classify customer locations into the correct tax district.
Setup
Enable Washington state sales tax districts
- Navigate to: Configuration > Settings
- Set option tax_district_method to Washington sales tax
- Set option tax_district_taxname, the tax name to dsplay on the invoice, or keep the default as Tax
- Run freeside-daily or freeside-tax-district-update -l to populate tax tables, and classify customers into their districts
Download tax tables and classify customer tax districts
The WA tax tables will be automatically populated, and customers in WA will be classified into their tax district he next time freeside-daily runs.
You don't have to wait for freeside-daily. The following command will update the tax tables and classify WA customers into their tax district.
sudo -u freeside /usr/bin/freeside-tax-district-update -l freeside_username
Changing Tax Name
You can change the display name for this tax by setting the config option tax_district_taxname. After changing the configuration value, the tax tables must be updated with the new taxname. This will happen automatically on the 1st of each month. Use freeside-tax-district-update to force this update sooner.
Administration
Tax table updates
freeside-daily will refresh the tax tables automatically on the first of each month.
Tax tables can be forcibly updated at any time using the freeside-tax-district-update utility.
If freeside is configured to use tax classes, with the enable_taxclasses configuration value, a complete copy of the Washington tax table will be created in every taxclass. If new tax classes are added later, the freeside-tax-district-update utility can be used to force an immediate rebuild of the tax table into the new tax class.
To view the tax table, navigate to Configuration > Billing > Locales and Tax Rates
Customer tax district classification
When an address record is created or edited, Freeside will ask the WA Dept. of Revenue API which tax district to use for the address.
If an invalid address is entereed, the tax district cannot be determined. The user will be advised to correct the address, or to manually choose a tax district to use.
Invoices cannot be generated for a WA customer missing a tax district. When a customer is missing a tax district:
- A notice appears on the customer page with instructions to fix
- Billing will not complete for this customer
- Freeside will retry, daily, to determine the customer tax district
- System log notices are generated about this problem. Subscribe to E-Mail alerts of these notices.
The freeside-tax-district-update tool can be used to force reclassification of every WA state address in cust_location. This may be useful if the state re-draws district lines, and all customers need to be reclassified.
Configure system log alerts
If a customer location record in the database lacks a tax district, freeside-daily will attempt to correct this situation. If that fails, Freeside will report an error to the system log.
Freeside will report another error every time freeside-daily runs, for every WA cust_location record without a tax district.
It is recommended to set two e-mail system log alerts: 1. log-level: error, log-context: wa_sales 2. log-level: error, log-context: tax_rate_update
Using log-level: info, somebody can be notified of all tax tables updates, and every successful tax district classification for a cust_location record.
See Freeside:3:Documentation:Administration#System_Log for help configuration system log alerts.
Upgrade from Version 3 to 4
Beginning with Freeside version 4, duplicate rows for identical tax districts in the cust_main_county table will block automatic tax table updates.
After upgrade, if an instance needs tax table repair, freeside-wa-tax-table-repair --check will display information on the problem tax rows. The duplicate rows can be merged with freeside-wa-tax-table-repair --merge or freeside-wa-tax-table-repair --merge-all
If a problem has developed with manually entered tax table rows for Universal Service Fund, this can be fixed with freeside-wa-tax-table-repair --fix-usf
After running these tools, it's recommended to force a tax table update with freeside-wa-tax-table-update -l
