=head1 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 C<add_sale> on the
+2. Each time a sale item is added to the invoice, call L</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.
+
+- 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
- C<collect> on each of the billed customers.
+ L<FS::cust_main::Billing/collect> on each of the billed customers.
- If not (the internal tax system, CCH):
-3. After adding all sale items, call C<calculate_taxes> on the TaxEngine to
+5. After adding all sale items, call L</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.
+6. Append the tax line items to the invoice.
+7. Update the invoice with the new charged amount and clear the pending flag.
=head1 CLASS METHODS
Creates an L<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.
+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.
=cut
sub new {
my $class = shift;
my %opt = @_;
+ my $conf = FS::Conf->new;
if ($class eq 'FS::TaxEngine') {
- my $conf = FS::Conf->new;
my $subclass = $conf->config('enable_taxproducts') || 'internal';
$class .= "::$subclass";
local $@;
eval "use $class";
die "couldn't load $class: $@\n" if $@;
}
- my $self = { items => [], taxes => {}, %opt };
+ my $self = { items => [], taxes => {}, conf => $conf, %opt };
bless $self, $class;
}
Adds the CUST_BILL_PKG object as a taxable sale on this invoice.
-=item calculate_taxes CUST_BILL
+=item calculate_taxes INVOICE
Calculates the taxes on the taxable sales and returns a list of
-L<FS::cust_bill_pkg> objects to add to the invoice. There is a base
-implementation of this, which calls the C<taxline> method to calculate
-each individual tax.
+L<FS::cust_bill_pkg> objects to add to the invoice. The base implementation
+is to call L</make_taxlines> to produce a list of "raw" tax line items,
+then L</consolidate_taxlines> to combine those with the same itemdesc.
=cut
sub calculate_taxes {
my $self = shift;
- my $conf = FS::Conf->new;
-
my $cust_bill = shift;
- my @tax_line_items;
- # keys are tax names (as printed on invoices / itemdesc )
- # values are arrayrefs of taxlines
- my %taxname;
+ my @raw_taxlines = $self->make_taxlines($cust_bill);
- # keys are taxnums
- # values are (cumulative) amounts
- my %tax_amount;
+ my @real_taxlines = $self->consolidate_taxlines(@raw_taxlines);
- # keys are taxnums
- # values are arrayrefs of cust_tax_exempt_pkg objects
- my %tax_exemption;
+ if ( $cust_bill and $cust_bill->get('invnum') ) {
+ $_->set('invnum', $cust_bill->get('invnum')) foreach @real_taxlines;
+ }
+ return \@real_taxlines;
+}
+
+sub make_taxlines {
+ my $self = shift;
+ my $conf = $self->{conf};
+
+ my $cust_bill = shift;
+
+ my @taxlines;
# For each distinct tax rate definition, calculate the tax and exemptions.
foreach my $taxnum ( keys %{ $self->{taxes} } ) {
# with their link records
die $taxline unless ref($taxline);
- push @{ $taxname{ $taxline->itemdesc } }, $taxline;
+ push @taxlines, $taxline;
} #foreach $taxnum
+ return @taxlines;
+}
+
+sub consolidate_taxlines {
+
+ my $self = shift;
+ my $conf = $self->{conf};
+
+ my @raw_taxlines = @_;
+ my @tax_line_items;
+
+ # keys are tax names (as printed on invoices / itemdesc )
+ # values are arrayrefs of taxlines
+ my %taxname;
+ # collate these by itemdesc
+ foreach my $taxline (@raw_taxlines) {
+ my $taxname = $taxline->itemdesc;
+ $taxname{$taxname} ||= [];
+ push @{ $taxname{$taxname} }, $taxline;
+ }
+
+ # keys are taxnums
+ # values are (cumulative) amounts
+ my %tax_amount;
+
my $link_table = $self->info->{link_table};
+
+ # Preconstruct cust_bill_pkg objects that will become the "final"
+ # taxlines for each name, so that we can reference them.
+ # (keys are taxnames)
+ my %real_taxline_named = map {
+ $_ => FS::cust_bill_pkg->new({
+ 'pkgnum' => 0,
+ 'recur' => 0,
+ 'sdate' => '',
+ 'edate' => '',
+ 'itemdesc' => $_
+ })
+ } keys %taxname;
+
# For each distinct tax name (the values set as $taxline->itemdesc),
# create a consolidated tax item with the total amount and all the links
# of all tax items that share that name.
foreach my $taxname ( keys %taxname ) {
my @tax_links;
- my $tax_cust_bill_pkg = FS::cust_bill_pkg->new({
- 'invnum' => $cust_bill->invnum,
- 'pkgnum' => 0,
- 'recur' => 0,
- 'sdate' => '',
- 'edate' => '',
- 'itemdesc' => $taxname,
- $link_table => \@tax_links,
- });
+ my $tax_cust_bill_pkg = $real_taxline_named{$taxname};
+ $tax_cust_bill_pkg->set( $link_table => \@tax_links );
my $tax_total = 0;
warn "adding $taxname\n" if $DEBUG > 1;
$tax_total += $taxitem->setup;
foreach my $link ( @{ $taxitem->get($link_table) } ) {
$link->set('tax_cust_bill_pkg', $tax_cust_bill_pkg);
+
+ # if the link represents tax on tax, also fix its taxable pointer
+ # to point to the "final" taxline
+ my $taxable_cust_bill_pkg = $link->get('taxable_cust_bill_pkg');
+ if (my $other_taxname = $taxable_cust_bill_pkg->itemdesc) {
+ $link->set('taxable_cust_bill_pkg',
+ $real_taxline_named{$other_taxname}
+ );
+ }
+
push @tax_links, $link;
}
} # foreach $taxitem
push @tax_line_items, $tax_cust_bill_pkg;
}
- \@tax_line_items;
+ @tax_line_items;
}
=head1 CLASS METHODS