Freeside:4:Documentation:Developer/FS/tax rate

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, CLASSES

Takes an arrayref of FS::cust_bill_pkg objects representing taxable line items, and an arrayref of charge classes ('setup', 'recur', '' for unclassified usage, or an FS::usage_class number). Calculates the tax on each item under this tax definition and returns a list of new FS::cust_bill_pkg_tax_rate_location objects for the taxes charged.

If the taxable objects are linked to an invoice, this will also calculate per-customer exemptions (cust_exempt and cust_taxname_exempt) and attach them to the line items in the 'cust_tax_exempt_pkg' pseudo-field.

For accurate calculation of per-customer or per-location taxes, ALL items appearing on the invoice (and subject to this tax) MUST be passed to this method together, and NO items from any other invoice should be included.

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