Freeside:4:Documentation:Developer/FS/TaxEngine

NAME

FS::TaxEngine - Base class for tax calculation engines.

USAGE

1. At the start of creating an invoice, create an FS::TaxEngine object. 2. Each time a sale item is added to the invoice, call "add_sale" on the TaxEngine. 3. Set the "pending" flag on the invoice. 4. Insert the invoice and its line items.

- If the TaxEngine is "batch" style (Billsoft): 5. After creating all invoices for the day, call FS::TaxEngine::process_tax_batch. This will create the tax items for all of the pending invoices, clear the "pending" flag, and call "collect" in FS/cust main/Billing|FS::cust_main::Billing#collect|"collect" in FS::cust_main::Billing on each of the billed customers.

- If not (the internal tax system, CCH): 5. After adding all sale items, call "calculate_taxes" on the TaxEngine to produce a list of tax line items. 6. Append the tax line items to the invoice. 7. Update the invoice with the new charged amount and clear the pending flag.

CLASS METHODS

class

Returns the class name for tax engines, according to the 'tax_data_vendor' configuration setting.

new 'cust_main' => CUST_MAIN, 'invoice_time' => TIME, OPTIONS...

Creates an FS::TaxEngine object. The subclass will be chosen by the 'tax_data_vendor' configuration setting.

CUST_MAIN and TIME are required. OPTIONS can include:

"cancel" => 1 to indicate that the package is being billed on cancellation.

"estimate" => 1 to indicate that this calculation is for tax estimation, and isn't an actual sale invoice, in case that matters.

info

Returns a hashref of metadata about this tax method, including: - batch: whether this is a batch-style engine (requires different usage) - override: whether this engine uses tax overrides - manual_tax_location: whether this engine requires the user to select a "tax location" separate from the address/city/state/zip fields - rate_table: the table that stores the tax rates (the 'taxline' method of that class will be used to calculate line-item taxes) - link_table: the table that links FS::cust_bill_pkg records for taxes to the rate_table entry that generated them, and to the item they represent tax on.

METHODS

add_sale CUST_BILL_PKG

Adds the CUST_BILL_PKG object as a taxable sale on this invoice.

calculate_taxes INVOICE

Calculates the taxes on the taxable sales and returns a list of FS::cust_bill_pkg objects to add to the invoice. The base implementation is to call "make_taxlines" to produce a list of "raw" tax line items, then "consolidate_taxlines" to combine those with the same itemdesc.

If this fails, it will throw an exception. (Accordingly it should not trap exceptions from internal methods that it calls, except to translate error messages into a more meaningful form.) If it succeeds, it MUST return an arrayref (even if the arrayref is empty).

CLASS METHODS

cust_tax_locations LOCATION

Given an FS::cust_location object (or a hash of location fields), returns a list of all tax jurisdiction locations that could possibly match it. This is meant for interactive use: the location editing UI displays the candidate locations to the user so they can choose the best match.

add_taxproduct DESCRIPTION

If the module allows manually adding tax products (categories of taxable items/services), this method will be called to do it. (If not, the UI in browse/part_pkg_taxproduct/* should prevent adding an unlisted tax product. That is the default behavior, so by default this method simply fails.)

DESCRIPTION is the contents of the taxproduct_description form input, which will normally be filled in by browse/part_pkg_taxproduct/*.

Must return the newly inserted part_pkg_taxproduct object on success, or a string on failure.

transfer_batch (batch-style only)

Submits the pending transaction batch for processing, receives the results, and appends the calculated taxes to all invoices that were included in the batch. Then clears their pending flags, and queues a job to run FS::cust_main::Billing::collect on each affected customer.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 266:

You forgot a '=back' before '=head1'

Around line 268:

'=item' outside of any '=over'