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

From Freeside
Jump to: navigation, search
m (Edit via perl MediaWiki framework (1.13))
 
m (Edit via perl MediaWiki framework (1.13))
Line 18: Line 18:
 
</code>
 
</code>
 
==DESCRIPTION==
 
==DESCRIPTION==
An FS::cust_tax_location object represents a mapping between a customer and a tax location. FS::cust_tax_location inherits from FS::Record. The following fields are currently supported:
+
An FS::cust_tax_location object represents a classification rule for determining a tax region code ('geocode') for a service location. These records are used when editing customer locations to help the user choose the correct tax jurisdiction code. The jurisdiction codes are actually defined in [[Freeside:3:Documentation:Developer/FS/tax rate location|FS::tax_rate_location]], and appear directly in records in [[Freeside:3:Documentation:Developer/FS/tax rate|FS::tax_rate]].
  
; custlocationnum
+
FS::cust_tax_location is used in tax calculation (for CCH) to determine "implied" geocodes for customers and locations that have a complete U.S. ZIP+4 code and thus can be exactly placed in a jurisdiction. For those that don't, the user is expected to choose the geocode when entering the customer record.
:primary key
+
 
; data_vendor
+
FS::cust_tax_location inherits from FS::Record. The following fields are currently supported:
:a tax data vendor
+
 
; zip; state; plus4hi
+
; custlocationnum - primary key; data_vendor - a tax data vendor and "style" of record; country - the two-letter country code; state - the two-letter state code (though CCH uses this differently; see QUIRKS); zip - an exact zip code (again, see QUIRKS); ziplo - the lower bound of the zip code range (requires zip to be null); ziphi - the upper bound of the zip code range (requires zip to be null); plus4lo - the lower bound of the last 4 zip code digits; plus4hi - the upper bound of the last 4 zip code digits; default_location - 'Y' when this record represents the default. The UI will list default locations before non-default locations.; geocode - the foreign key into [[Freeside:3:Documentation:Developer/FS/part pkg tax rate|FS::part_pkg_tax_rate]], [[Freeside:3:Documentation:Developer/FS/tax rate|FS::tax_rate]], [[Freeside:3:Documentation:Developer/FS/tax rate location|FS::tax_rate_location]], etc.
:the upper bound of the last 4 zip code digits
 
; plus4lo
 
:the lower bound of the last 4 zip code digits
 
; default_location
 
:'Y' when this record represents the default for zip
 
; geocode - the foreign key into FS&#58;&#58;part_pkg_tax_rate and FS&#58;&#58;tax_rate
 
 
==METHODS==
 
==METHODS==
 
; new HASHREF
 
; new HASHREF
Line 44: Line 38:
 
; check
 
; check
 
:Checks all fields to make sure this is a valid cust_tax_location. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
 
:Checks all fields to make sure this is a valid cust_tax_location. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
 +
 +
==SUBROUTINES==
 +
; process_batch_import JOB, PARAMS
 +
:Starts a batch import given JOB (an [[Freeside:3:Documentation:Developer/FS/queue|FS::queue]]) and PARAMS (a Base64-Storable hash). PARAMS should contain 'format' and 'uploaded_files'.
 +
 +
:Currently only usable for Billsoft imports; CCH's agglomeration of update files need to be imported through [[Freeside:3:Documentation:Developer/FS/tax rate/process batch import|FS::tax_rate::process_batch_import]].
 +
 +
==QUIRKS==
 +
CCH doesn't have a "country" field; for addresses in Canada it uses state = 'CN', and zip = the one-letter postal code prefix for the province. Or maybe that's just our CCH implementation. This doesn't apply to Billsoft, and shouldn't apply to any other tax vendor that may somehow be implemented.
 +
 +
CCH also has two styles of records in this table: cch and cch-zip. cch records define a unique
  
 
==BUGS==
 
==BUGS==
The author should be informed of any you find.
+
CCH clutter.
  
 
==SEE ALSO==
 
==SEE ALSO==
 
[[Freeside:3:Documentation:Developer/FS/Record|FS::Record]], schema.html from the base documentation.
 
[[Freeside:3:Documentation:Developer/FS/Record|FS::Record]], schema.html from the base documentation.

Revision as of 06:31, 24 March 2015

NAME

FS::cust_tax_location - Object methods for cust_tax_location records

SYNOPSIS

 use FS::cust_tax_location;

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

 $error = $record->insert;

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

 $error = $record->delete;

 $error = $record->check;

DESCRIPTION

An FS::cust_tax_location object represents a classification rule for determining a tax region code ('geocode') for a service location. These records are used when editing customer locations to help the user choose the correct tax jurisdiction code. The jurisdiction codes are actually defined in FS::tax_rate_location, and appear directly in records in FS::tax_rate.

FS::cust_tax_location is used in tax calculation (for CCH) to determine "implied" geocodes for customers and locations that have a complete U.S. ZIP+4 code and thus can be exactly placed in a jurisdiction. For those that don't, the user is expected to choose the geocode when entering the customer record.

FS::cust_tax_location inherits from FS::Record. The following fields are currently supported:

custlocationnum - primary key; data_vendor - a tax data vendor and "style" of record; country - the two-letter country code; state - the two-letter state code (though CCH uses this differently; see QUIRKS); zip - an exact zip code (again, see QUIRKS); ziplo - the lower bound of the zip code range (requires zip to be null); ziphi - the upper bound of the zip code range (requires zip to be null); plus4lo - the lower bound of the last 4 zip code digits; plus4hi - the upper bound of the last 4 zip code digits; default_location - 'Y' when this record represents the default. The UI will list default locations before non-default locations.; geocode - the foreign key into FS::part_pkg_tax_rate, FS::tax_rate, FS::tax_rate_location, etc.

METHODS

new HASHREF
Creates a new cust_tax_location. To add the cust_tax_location to the database, see "insert".
Note that this stores the hash reference, not a distinct copy of the hash it points to. You can ask the object for a copy with the hash method.
insert
Adds this record to the database. If there is an error, returns the error, otherwise returns false.
delete
Delete this record from the database.
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 cust_tax_location. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.

SUBROUTINES

process_batch_import JOB, PARAMS
Starts a batch import given JOB (an FS::queue) and PARAMS (a Base64-Storable hash). PARAMS should contain 'format' and 'uploaded_files'.
Currently only usable for Billsoft imports; CCH's agglomeration of update files need to be imported through FS::tax_rate::process_batch_import.

QUIRKS

CCH doesn't have a "country" field; for addresses in Canada it uses state = 'CN', and zip = the one-letter postal code prefix for the province. Or maybe that's just our CCH implementation. This doesn't apply to Billsoft, and shouldn't apply to any other tax vendor that may somehow be implemented.

CCH also has two styles of records in this table: cch and cch-zip. cch records define a unique

BUGS

CCH clutter.

SEE ALSO

FS::Record, schema.html from the base documentation.