Freeside:3: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.

- If the TaxEngine is "batch" style (Billsoft): 3. Set the "pending" flag on the invoice. 4. Insert the invoice and its line items. 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 on each of the billed customers.

- If not (the internal tax system, CCH): 3. After adding all sale items, call calculate_taxes on the TaxEngine to produce a list of tax line items. 4. Append the tax line items to the invoice. 5. Insert the invoice.

CLASS METHODS

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

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

CUST_MAIN and TIME are required. OPTIONS can include "cancel" => 1 to indicate that the package is being billed on cancellation.

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 CUST_BILL

Calculates the taxes on the taxable sales and returns a list of FS::cust_bill_pkg objects to add to the invoice. There is a base implementation of this, which calls the taxline method to calculate each individual tax.

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 191:

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

Around line 193:

'=item' outside of any '=over'