Difference between revisions of "Freeside:3:Documentation:Developer/FS/tax rate"

From Freeside
Jump to: navigation, search
m (Edit via perl MediaWiki framework (1.13))
m (Edit via perl MediaWiki framework (1.13))
Line 29: Line 29:
 
:a location code provided by a tax authority
 
:a location code provided by a tax authority
 
; taxclassnum
 
; taxclassnum
:a foreign key into FS::tax_class - the type of tax referenced but FS::part_pkg_taxrate eitem effective_date
+
:a foreign key into FS::tax_class - the type of tax referenced by FS::part_pkg_taxrate
 
+
; effective_date
 
:the time after which the tax applies
 
:the time after which the tax applies
 
; tax
 
; tax
Line 96: Line 96:
 
; passtype_name
 
; passtype_name
 
:Returns the human understandable value associated with the passtype column
 
:Returns the human understandable value associated with the passtype column
; taxline TAXABLES_ARRAYREF, [ OPTION => VALUE ... ]
+
; taxline_cch TAXABLES, [ OPTIONSHASH ]
:Takes an arrayref of [[Freeside:3:Documentation:Developer/FS/cust bill pkg|FS::cust_bill_pkg]] objects representing taxable line items, and returns some number of new [[Freeside:3:Documentation:Developer/FS/cust bill pkg|FS::cust_bill_pkg]] objects representing the tax on them under this tax rate. Each returned object will correspond to a single input line item.
+
:Returns a listref of a name and an amount of tax calculated for the list of packages/amounts referenced by TAXABLES. If an error occurs, a message is returned as a scalar.
 
 
:For accurate calculation of per-customer or per-location taxes, ALL items appearing on the invoice MUST be passed to this method together.
 
 
 
:Optionally, any of the [[Freeside:3:Documentation:Developer/FS/cust bill pkg|FS::cust_bill_pkg]] objects may be followed in the array by a charge class: 'setup', 'recur', '' (for unclassified usage), or an integer denoting an [[Freeside:3:Documentation:Developer/FS/usage class|FS::usage_class]] number. In this case, the tax will only be charged on that portion of the line item.
 
 
 
:Each returned object will have a pseudo-field, "cust_bill_pkg_tax_rate_location", containing a single [[Freeside:3:Documentation:Developer/FS/cust bill pkg tax rate location|FS::cust_bill_pkg_tax_rate_location]] object. This will in turn have a "taxable_cust_bill_pkg" pseudo-field linking it to one of the taxable items. All of these links must be resolved as the objects are inserted.
 
 
 
:If the tax is disabled, this method will return nothing. Be prepared for that.
 
 
 
:In addition to calculating the tax for the line items, this will calculate tax exemptions and attach them to the line items. ''Currently this only supports customer exemptions.''
 
 
 
:Options may include 'custnum' and 'invoice_time' in case the cust_bill_pkg objects belong to an invoice that hasn't been inserted yet.
 
 
 
:The 'exemptions' option allowed in [[Freeside:3:Documentation:Developer/FS/cust main county/taxline|FS::cust_main_county::taxline]] does nothing here, since monthly exemptions aren't supported.
 
 
; tax_on_tax CUST_LOCATION
 
; tax_on_tax CUST_LOCATION
 
:Returns a list of taxes which are candidates for taxing taxes for the given service location (see [[Freeside:3:Documentation:Developer/FS/cust location|FS::cust_location]])
 
:Returns a list of taxes which are candidates for taxing taxes for the given service location (see [[Freeside:3:Documentation:Developer/FS/cust location|FS::cust_location]])
 
; tax_rate_location
 
; tax_rate_location
 
:Returns an object representing the location associated with this tax (see [[Freeside:3:Documentation:Developer/FS/tax rate location|FS::tax_rate_location]])
 
:Returns an object representing the location associated with this tax (see [[Freeside:3:Documentation:Developer/FS/tax rate location|FS::tax_rate_location]])
 +
; find_or_insert
 +
:Finds an existing tax definition matching the data_vendor, taxname, taxclassnum, and geocode of this one, if one exists, and sets the contents of this tax rate equal to that one (including its taxnum). If an existing definition is not found, inserts this one. Returns an error string if inserting a record failed.
  
 
==SUBROUTINES==
 
==SUBROUTINES==
Line 121: Line 109:
 
:Load a batch import as a queued JSRPC job
 
:Load a batch import as a queued JSRPC job
 
; process_download_and_reload
 
; process_download_and_reload
:Download and process a tax update as a queued JSRPC job after wiping the existing wipable tax data.
+
:Download and process a tax update as a queued JSRPC job after wiping the existing wipeable tax data.
 
; process_batch_reload
 
; process_batch_reload
 
:Load and process a tax update from the provided files as a queued JSRPC job after wiping the existing wipable tax data.
 
:Load and process a tax update from the provided files as a queued JSRPC job after wiping the existing wipable tax data.
Line 139: Line 127:
 
==BUGS==
 
==BUGS==
 
<code>
 
<code>
 +
  Highly specific to CCH taxes.  This should arguably go in some kind of
 +
  subclass (FS::tax_rate::CCH) with auto-reblessing, similar to part_pkg
 +
  subclasses.  But currently there aren't any other options, so.
 +
 
   Mixing automatic and manual editing works poorly at present.
 
   Mixing automatic and manual editing works poorly at present.
 
   
 
   
 
   Tax liability calculations take too long and arguably don't belong here.
 
   Tax liability calculations take too long and arguably don't belong here.
 
   Tax liability report generation not entirely safe (escaped).
 
   Tax liability report generation not entirely safe (escaped).
 +
 +
  Sparse documentation.
 
</code>
 
</code>
 
==SEE ALSO==
 
==SEE ALSO==
 
[[Freeside:3:Documentation:Developer/FS/Record|FS::Record]], [[Freeside:3:Documentation:Developer/FS/cust location|FS::cust_location]], [[Freeside:3:Documentation:Developer/FS/cust bill|FS::cust_bill]]
 
[[Freeside:3:Documentation:Developer/FS/Record|FS::Record]], [[Freeside:3:Documentation:Developer/FS/cust location|FS::cust_location]], [[Freeside:3:Documentation:Developer/FS/cust bill|FS::cust_bill]]

Revision as of 11:01, 30 March 2015

NAME

FS::tax_rate - Object methods for tax_rate objects

SYNOPSIS

 use FS::tax_rate;

 $record = new FS::tax_rate \%hash;
 $record = new FS::tax_rate { 'column' => 'value' };

 $error = $record->insert;

 $error = $new_record->replace($old_record);

 $error = $record->delete;

 $error = $record->check;

DESCRIPTION

An FS::tax_rate object represents a tax rate, defined by locale. FS::tax_rate inherits from FS::Record. The following fields are currently supported:

taxnum
primary key (assigned automatically for new tax rates)
geocode
a geographic location code provided by a tax data vendor
data_vendor
the tax data vendor
location
a location code provided by a tax authority
taxclassnum
a foreign key into FS::tax_class - the type of tax referenced by FS::part_pkg_taxrate
effective_date
the time after which the tax applies
tax
percentage
excessrate
second bracket percentage
taxbase
the amount to which the tax applies (first bracket)
taxmax
a cap on the amount of tax if a cap exists
usetax
percentage on out of jurisdiction purchases
useexcessrate
second bracket percentage on out of jurisdiction purchases
unittype
one of the values in %tax_unittypes
fee
amount of tax per unit
excessfee
second bracket amount of tax per unit
feebase
the number of units to which the fee applies (first bracket)
feemax
the most units to which fees apply (first and second brackets)
maxtype
a value from %tax_maxtypes indicating how brackets accumulate (i.e. monthly, per invoice, etc)
taxname
if defined, printed on invoices instead of "Tax"
taxauth
a value from %tax_authorities
basetype
a value from %tax_basetypes indicating the tax basis
passtype
a value from %tax_passtypes indicating how the tax should displayed to the customer
passflag
'Y', 'N', or blank indicating the tax can be passed to the customer
setuptax
if 'Y', this tax does not apply to setup fees
recurtax
if 'Y', this tax does not apply to recurring fees
manual
if 'Y', has been manually edited

METHODS

new HASHREF
Creates a new tax rate. To add the tax rate to the database, see "insert".
insert
Adds this tax rate to the database. If there is an error, returns the error, otherwise returns false.
delete
Deletes this tax rate from the database. If there is an error, returns the error, otherwise returns false.
replace OLD_RECORD
Replaces the OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
check
Checks all fields to make sure this is a valid tax rate. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
taxclass_description
Returns the human understandable value associated with the related FS::tax_class.
unittype_name
Returns the human understandable value associated with the unittype column
maxtype_name
Returns the human understandable value associated with the maxtype column.
basetype_name
Returns the human understandable value associated with the basetype column
taxauth_name
Returns the human understandable value associated with the taxauth column
passtype_name
Returns the human understandable value associated with the passtype column
taxline_cch TAXABLES, [ OPTIONSHASH ]
Returns a listref of a name and an amount of tax calculated for the list of packages/amounts referenced by TAXABLES. If an error occurs, a message is returned as a scalar.
tax_on_tax CUST_LOCATION
Returns a list of taxes which are candidates for taxing taxes for the given service location (see FS::cust_location)
tax_rate_location
Returns an object representing the location associated with this tax (see FS::tax_rate_location)
find_or_insert
Finds an existing tax definition matching the data_vendor, taxname, taxclassnum, and geocode of this one, if one exists, and sets the contents of this tax rate equal to that one (including its taxnum). If an existing definition is not found, inserts this one. Returns an error string if inserting a record failed.

SUBROUTINES

batch_import; process_batch_import
Load a batch import as a queued JSRPC job
process_download_and_reload
Download and process a tax update as a queued JSRPC job after wiping the existing wipeable tax data.
process_batch_reload
Load and process a tax update from the provided files as a queued JSRPC job after wiping the existing wipable tax data.
process_download_and_update
Download and process a tax update as a queued JSRPC job
browse_queries PARAMS
Returns a list consisting of a hashref suited for use as the argument to qsearch, and sql query string. Each is based on the PARAMS hashref of keys and values which frequently would be passed as scalar($cgi-Vars)> from a form. This conveniently creates the query hashref and count_query string required by the browse and search elements. As a side effect, the PARAMS hashref is untainted and keys with unexpected values are removed.
queue_liability_report PARAMS
Launches a tax liability report.
PARAMS needs to be a base64-encoded Storable hash containing: - beginning: the start date, as a user-readable string (not a timestamp). - end: the end date of the report, likewise. - agentnum: the agent to limit the report to, if any.
generate_liability_report PARAMS
Generates a tax liability report. PARAMS must include:
- beginning, as a timestamp - ending, as a timestamp - p: the Freeside root URL, for generating links - agentnum (optional)

BUGS

 Highly specific to CCH taxes.  This should arguably go in some kind of 
 subclass (FS::tax_rate::CCH) with auto-reblessing, similar to part_pkg
 subclasses.  But currently there aren't any other options, so.

 Mixing automatic and manual editing works poorly at present.

 Tax liability calculations take too long and arguably don't belong here.
 Tax liability report generation not entirely safe (escaped).

 Sparse documentation.

SEE ALSO

FS::Record, FS::cust_location, FS::cust_bill