1 package FS::Report::Tax;
5 use FS::Record qw(dbh qsearch qsearchs group_concat_sql);
6 use Date::Format qw( time2str );
12 =item report_internal OPTIONS
14 Constructor. Generates a tax report using the internal tax rate system
15 (L<FS::cust_main_county>).
19 - beginning, ending: the date range as Unix timestamps.
20 - taxname: the name of the tax (corresponds to C<cust_bill_pkg.itemdesc>).
21 - country: the country code.
24 - agentnum: limit to this agentnum.num.
25 - breakdown: hashref of the fields to group by. Keys can be 'city', 'district',
26 'pkgclass', or 'taxclass'; values should be true.
27 - debug: sets the debug level. 1 will warn the data collected for the report;
28 2 will also warn all of the SQL statements.
36 $DEBUG ||= $opt{debug};
38 my $conf = new FS::Conf;
40 my($beginning, $ending) = @opt{'beginning', 'ending'};
42 my ($taxname, $country, %breakdown);
44 # taxname can contain arbitrary punctuation; escape it properly and
45 # include $taxname unquoted elsewhere
46 $taxname = dbh->quote($opt{'taxname'});
48 if ( $opt{country} =~ /^(\w\w)$/ ) {
51 die "country required";
54 # %breakdown: short name => field identifier
55 # null classnum should remain null, not be converted to zero
57 'taxclass' => 'cust_main_county.taxclass',
58 'pkgclass' => 'COALESCE(part_fee.classnum,part_pkg.classnum)',
59 'city' => 'cust_main_county.city',
60 'district' => 'cust_main_county.district',
61 'state' => 'cust_main_county.state',
62 'county' => 'cust_main_county.county',
64 foreach (qw(taxclass pkgclass city district)) {
65 delete $breakdown{$_} unless $opt{breakdown}->{$_};
68 my $join_cust = ' JOIN cust_bill USING ( invnum )
69 LEFT JOIN cust_main USING ( custnum ) ';
71 my $join_cust_pkg = $join_cust.
72 ' LEFT JOIN cust_pkg USING ( pkgnum )
73 LEFT JOIN part_pkg USING ( pkgpart )
74 LEFT JOIN part_fee USING ( feepart ) ';
76 my $from_join_cust_pkg = " FROM cust_bill_pkg $join_cust_pkg ";
78 # all queries MUST be linked to both cust_bill and cust_main_county
80 # Either or both of these can be used to link cust_bill_pkg to
81 # cust_main_county. This one links a taxed line item (billpkgnum) to a tax rate
82 # (taxnum), and gives the amount of tax charged on that line item under that
83 # rate (as tax_amount).
84 my $pkg_tax = "SELECT SUM(amount) as tax_amount, taxnum, ".
85 "taxable_billpkgnum AS billpkgnum ".
86 "FROM cust_bill_pkg_tax_location JOIN cust_bill_pkg USING (billpkgnum) ".
87 "GROUP BY taxable_billpkgnum, taxnum";
89 # This one links a tax-exempted line item (billpkgnum) to a tax rate
90 # (taxnum), and gives the amount of the tax exemption. EXEMPT_WHERE must
91 # be replaced with an expression to further limit the tax exemptions
92 # that will be included, or "TRUE" to not limit them.
94 # Note that tax exemptions with non-null creditbillpkgnum are always
95 # excluded. Those are "negative exemptions" created by crediting a sale
96 # that had received an exemption.
97 my $pkg_tax_exempt = "SELECT SUM(amount) AS exempt_charged, billpkgnum, taxnum ".
98 "FROM cust_tax_exempt_pkg WHERE
100 AND cust_tax_exempt_pkg.creditbillpkgnum IS NULL
101 GROUP BY billpkgnum, taxnum";
103 my $where = "WHERE cust_bill._date >= $beginning AND cust_bill._date <= $ending ".
104 "AND COALESCE(cust_main_county.taxname,'Tax') = $taxname ".
105 "AND cust_main_county.country = '$country'";
106 # SELECT/GROUP clauses for first-level queries
107 my $select = "SELECT ";
108 my $group = "GROUP BY ";
109 foreach (qw(pkgclass taxclass state county city district)) {
110 if ( $breakdown{$_} ) {
111 $select .= "$breakdown{$_} AS $_, ";
112 $group .= "$breakdown{$_}, ";
114 $select .= "NULL AS $_, ";
117 $select .= group_concat_sql('DISTINCT(cust_main_county.taxnum)', ',') .
121 # SELECT/GROUP clauses for second-level (totals) queries
122 # breakdown by package class only, if anything
123 my $select_all = "SELECT NULL AS pkgclass, ";
125 if ( $breakdown{pkgclass} ) {
126 $select_all = "SELECT $breakdown{pkgclass} AS pkgclass, ";
127 $group_all = "GROUP BY $breakdown{pkgclass}";
129 $select_all .= group_concat_sql('DISTINCT(cust_main_county.taxnum)', ',') .
133 if ( $opt{agentnum} and $opt{agentnum} =~ /^(\d+)$/ ) {
135 my $agent = qsearchs('agent', { 'agentnum' => $agentnum } );
136 die "agent not found" unless $agent;
137 $where .= " AND cust_main.agentnum = $agentnum";
141 '(cust_bill_pkg.pkgnum != 0 OR cust_bill_pkg.feepart IS NOT NULL)';
143 # one query for each column of the report
144 # plus separate queries for the totals row
147 # SALES QUERIES (taxable sales, all types of exempt sales)
151 my $exempt = "$select SUM(exempt_charged)
152 FROM cust_main_county
153 JOIN ($pkg_tax_exempt) AS pkg_tax_exempt
155 JOIN cust_bill_pkg USING (billpkgnum)
156 $join_cust_pkg $where AND $nottax
159 my $all_exempt = "$select_all SUM(exempt_charged)
160 FROM cust_main_county
161 JOIN ($pkg_tax_exempt) AS pkg_tax_exempt
163 JOIN cust_bill_pkg USING (billpkgnum)
164 $join_cust_pkg $where AND $nottax
167 # sales to tax-exempt customers
168 $sql{exempt_cust} = $exempt;
169 $sql{exempt_cust} =~ s/EXEMPT_WHERE/exempt_cust = 'Y' OR exempt_cust_taxname = 'Y'/;
170 $all_sql{exempt_cust} = $all_exempt;
171 $all_sql{exempt_cust} =~ s/EXEMPT_WHERE/exempt_cust = 'Y' OR exempt_cust_taxname = 'Y'/;
173 # sales of tax-exempt packages
174 $sql{exempt_pkg} = $exempt;
175 $sql{exempt_pkg} =~ s/EXEMPT_WHERE/exempt_setup = 'Y' OR exempt_recur = 'Y'/;
176 $all_sql{exempt_pkg} = $all_exempt;
177 $all_sql{exempt_pkg} =~ s/EXEMPT_WHERE/exempt_setup = 'Y' OR exempt_recur = 'Y'/;
179 # monthly per-customer exemptions
180 $sql{exempt_monthly} = $exempt;
181 $sql{exempt_monthly} =~ s/EXEMPT_WHERE/exempt_monthly = 'Y'/;
182 $all_sql{exempt_monthly} = $all_exempt;
183 $all_sql{exempt_monthly} =~ s/EXEMPT_WHERE/exempt_monthly = 'Y'/;
185 # credits applied to taxable sales
186 # Note that negative exemptions (from exempt sales being credited) are NOT
187 # counted when calculating the exempt amount. (See above.) Therefore we need
188 # to NOT include any credits against exempt sales in this amount, either.
189 # These two subqueries implement that. They have joins to cust_credit_bill
190 # and cust_bill so that credits can be filtered by application date if
193 # Each row here is the sum of credits applied to a line item.
195 "SELECT billpkgnum, SUM(cust_credit_bill_pkg.amount) AS credited
196 FROM cust_credit_bill_pkg
197 JOIN cust_credit_bill USING (creditbillnum)
198 JOIN cust_bill USING (invnum)
199 WHERE cust_bill._date >= $beginning AND cust_bill._date <= $ending
203 # Each row here is the sum of negative exemptions applied to a combination
204 # of line item and tax definition.
206 "SELECT cust_credit_bill_pkg.billpkgnum, taxnum,
207 0 - SUM(cust_tax_exempt_pkg.amount) AS exempt_credited
208 FROM cust_credit_bill_pkg
209 LEFT JOIN cust_tax_exempt_pkg USING (creditbillpkgnum)
210 JOIN cust_credit_bill USING (creditbillnum)
211 JOIN cust_bill USING (invnum)
212 WHERE cust_bill._date >= $beginning AND cust_bill._date <= $ending
213 GROUP BY cust_credit_bill_pkg.billpkgnum, taxnum
216 if ( $opt{credit_date} eq 'cust_credit_bill' ) {
217 $sales_credit =~ s/cust_bill._date/cust_credit_bill._date/g;
218 $exempt_credit =~ s/cust_bill._date/cust_credit_bill._date/g;
221 $sql{sales_credited} = "$select
222 SUM(COALESCE(credited, 0) - COALESCE(exempt_credited, 0))
223 FROM cust_main_county
224 JOIN ($pkg_tax) AS pkg_tax USING (taxnum)
225 JOIN cust_bill_pkg USING (billpkgnum)
226 LEFT JOIN ($sales_credit) AS sales_credit USING (billpkgnum)
227 LEFT JOIN ($exempt_credit) AS exempt_credit USING (billpkgnum, taxnum)
228 $join_cust_pkg $where AND $nottax
232 $all_sql{sales_credited} = "$select_all
233 SUM(COALESCE(credited, 0) - COALESCE(exempt_credited, 0))
234 FROM cust_main_county
235 JOIN ($pkg_tax) AS pkg_tax USING (taxnum)
236 JOIN cust_bill_pkg USING (billpkgnum)
237 LEFT JOIN ($sales_credit) AS sales_credit USING (billpkgnum)
238 LEFT JOIN ($exempt_credit) AS exempt_credit USING (billpkgnum, taxnum)
239 $join_cust_pkg $where AND $nottax
244 $sql{taxable} = "$select
245 SUM(cust_bill_pkg.setup + cust_bill_pkg.recur
246 - COALESCE(exempt_charged, 0)
247 - COALESCE(credited, 0)
248 + COALESCE(exempt_credited, 0)
250 FROM cust_main_county
251 JOIN ($pkg_tax) AS pkg_tax USING (taxnum)
252 JOIN cust_bill_pkg USING (billpkgnum)
253 LEFT JOIN ($pkg_tax_exempt) AS pkg_tax_exempt USING (billpkgnum, taxnum)
254 LEFT JOIN ($sales_credit) AS sales_credit USING (billpkgnum)
255 LEFT JOIN ($exempt_credit) AS exempt_credit USING (billpkgnum, taxnum)
256 $join_cust_pkg $where AND $nottax
259 $all_sql{taxable} = "$select_all
260 SUM(cust_bill_pkg.setup + cust_bill_pkg.recur
261 - COALESCE(exempt_charged, 0)
262 - COALESCE(credited, 0)
263 + COALESCE(exempt_credited, 0)
265 FROM cust_main_county
266 JOIN ($pkg_tax) AS pkg_tax USING (taxnum)
267 JOIN cust_bill_pkg USING (billpkgnum)
268 LEFT JOIN ($pkg_tax_exempt) AS pkg_tax_exempt USING (billpkgnum, taxnum)
269 LEFT JOIN ($sales_credit) AS sales_credit USING (billpkgnum)
270 LEFT JOIN ($exempt_credit) AS exempt_credit USING (billpkgnum, taxnum)
271 $join_cust_pkg $where AND $nottax
274 $sql{taxable} =~ s/EXEMPT_WHERE/TRUE/; # unrestricted
275 $all_sql{taxable} =~ s/EXEMPT_WHERE/TRUE/;
277 # estimated tax (taxable * rate)
278 $sql{estimated} = "$select
279 SUM(cust_main_county.tax / 100 *
280 (cust_bill_pkg.setup + cust_bill_pkg.recur
281 - COALESCE(exempt_charged, 0)
282 - COALESCE(credited, 0)
283 + COALESCE(exempt_credited, 0)
286 FROM cust_main_county
287 JOIN ($pkg_tax) AS pkg_tax USING (taxnum)
288 JOIN cust_bill_pkg USING (billpkgnum)
289 LEFT JOIN ($pkg_tax_exempt) AS pkg_tax_exempt USING (billpkgnum, taxnum)
290 LEFT JOIN ($sales_credit) AS sales_credit USING (billpkgnum)
291 LEFT JOIN ($exempt_credit) AS exempt_credit USING (billpkgnum, taxnum)
292 $join_cust_pkg $where AND $nottax
295 $all_sql{estimated} = "$select_all
296 SUM(cust_main_county.tax / 100 *
297 (cust_bill_pkg.setup + cust_bill_pkg.recur
298 - COALESCE(exempt_charged, 0)
299 - COALESCE(credited, 0)
300 + COALESCE(exempt_credited, 0)
303 FROM cust_main_county
304 JOIN ($pkg_tax) AS pkg_tax USING (taxnum)
305 JOIN cust_bill_pkg USING (billpkgnum)
306 LEFT JOIN ($pkg_tax_exempt) AS pkg_tax_exempt USING (billpkgnum, taxnum)
307 LEFT JOIN ($sales_credit) AS sales_credit USING (billpkgnum)
308 LEFT JOIN ($exempt_credit) AS exempt_credit USING (billpkgnum, taxnum)
309 $join_cust_pkg $where AND $nottax
312 $sql{estimated} =~ s/EXEMPT_WHERE/TRUE/; # unrestricted
313 $all_sql{estimated} =~ s/EXEMPT_WHERE/TRUE/;
315 # there isn't one for 'sales', because we calculate sales by adding up
316 # the taxable and exempt columns.
318 # TAX QUERIES (billed tax, credited tax, collected tax)
322 # join cust_bill_pkg to cust_main_county via cust_bill_pkg_tax_location
323 my $taxfrom = " FROM cust_bill_pkg
325 LEFT JOIN cust_bill_pkg_tax_location USING ( billpkgnum )
326 LEFT JOIN cust_main_county USING ( taxnum )";
328 if ( $breakdown{pkgclass} ) {
329 # If we're not grouping by package class, this is unnecessary, and
330 # probably really expensive.
331 # Remember that fees also have package classes.
333 LEFT JOIN cust_bill_pkg AS taxable
334 ON (cust_bill_pkg_tax_location.taxable_billpkgnum = taxable.billpkgnum)
335 LEFT JOIN cust_pkg ON (taxable.pkgnum = cust_pkg.pkgnum)
336 LEFT JOIN part_pkg USING (pkgpart)
337 LEFT JOIN part_fee ON (taxable.feepart = part_fee.feepart) ";
340 my $istax = "cust_bill_pkg.pkgnum = 0 and cust_bill_pkg.feepart is null";
342 $sql{tax} = "$select SUM(cust_bill_pkg_tax_location.amount)
347 $all_sql{tax} = "$select_all SUM(cust_bill_pkg_tax_location.amount)
352 # sum of credits applied against billed tax
353 # ($creditfrom includes join of taxable item to part_pkg/part_fee if
354 # with_pkgclass is on)
355 my $creditfrom = $taxfrom .
356 ' JOIN cust_credit_bill_pkg USING (billpkgtaxlocationnum)' .
357 ' JOIN cust_credit_bill USING (creditbillnum)';
358 my $creditwhere = $where .
359 ' AND billpkgtaxratelocationnum IS NULL';
361 # if the credit_date option is set to application date, change
362 # $creditwhere accordingly
363 if ( $opt{credit_date} eq 'cust_credit_bill' ) {
364 $creditwhere =~ s/cust_bill._date/cust_credit_bill._date/g;
367 $sql{tax_credited} = "$select SUM(cust_credit_bill_pkg.amount)
369 $creditwhere AND $istax
372 $all_sql{tax_credited} = "$select_all SUM(cust_credit_bill_pkg.amount)
374 $creditwhere AND $istax
378 # this suffers from the same ambiguity as anything else that applies
379 # received payments to specific packages, but in reality the discrepancy
380 # should be minimal since people either pay their bill or don't.
381 # the join is on billpkgtaxlocationnum to avoid cross-producting.
383 my $paidfrom = $taxfrom .
384 ' JOIN cust_bill_pay_pkg'.
385 ' ON (cust_bill_pay_pkg.billpkgtaxlocationnum ='.
386 ' cust_bill_pkg_tax_location.billpkgtaxlocationnum)';
388 $sql{tax_paid} = "$select SUM(cust_bill_pay_pkg.amount)
393 $all_sql{tax_paid} = "$select_all SUM(cust_bill_pay_pkg.amount)
400 # note that we use keys(%sql) here and keys(%all_sql) later. nothing
401 # obligates us to use the same set of variables for the total query
402 # as for the individual category queries
403 foreach my $k (keys(%sql)) {
405 warn "\n".uc($k).":\n".$stmt."\n" if $DEBUG > 1;
406 my $sth = dbh->prepare($stmt);
407 # eight columns: pkgclass, taxclass, state, county, city, district
408 # taxnums (comma separated), value
410 or die "failed to execute $k query: ".$sth->errstr;
411 while ( my $row = $sth->fetchrow_arrayref ) {
413 {$row->[0]} # pkgclass
414 {$row->[1] # taxclass
415 || ($breakdown{taxclass} ? 'Unclassified' : '')}
417 {$row->[3] ? $row->[3] . ' County' : ''} # county
419 {$row->[5]} # district
421 push @$bin, [ $k, $row->[6], $row->[7] ];
424 warn "DATA:\n".Dumper(\%data) if $DEBUG;
426 foreach my $k (keys %all_sql) {
427 warn "\nTOTAL ".uc($k).":\n".$all_sql{$k}."\n" if $DEBUG;
428 my $sth = dbh->prepare($all_sql{$k});
429 # three columns: pkgclass, taxnums (comma separated), value
431 or die "failed to execute $k totals query: ".$sth->errstr;
432 while ( my $row = $sth->fetchrow_arrayref ) {
433 my $bin = $total{$row->[0]} ||= [];
434 push @$bin, [ $k, $row->[1], $row->[2] ];
437 warn "TOTALS:\n".Dumper(\%total) if $DEBUG > 1;
439 # $data{$pkgclass}{$taxclass}{$state}{$county}{$city}{$district} = [
440 # [ 'taxable', taxnums, amount ],
441 # [ 'exempt_cust', taxnums, amount ],
444 # non-requested grouping levels simply collapse into key = ''
446 # the much-maligned "out of taxable region"...
447 # find sales that are not linked to any tax with this name
448 # but are still inside the date range/agent criteria.
450 # This doesn't use $select_all/$group_all because we want a single number,
451 # not a breakdown by pkgclass. Unless someone needs that eventually,
452 # in which case we'll turn it into an %all_sql query.
455 "WHERE cust_bill._date >= $beginning AND cust_bill._date <= $ending";
457 $outside_where .= " AND cust_main.agentnum = $agentnum";
459 my $sql_outside = "SELECT SUM(cust_bill_pkg.setup + cust_bill_pkg.recur)
465 SELECT 1 FROM cust_tax_exempt_pkg
466 JOIN cust_main_county USING (taxnum)
467 WHERE cust_tax_exempt_pkg.billpkgnum = cust_bill_pkg.billpkgnum
468 AND COALESCE(cust_main_county.taxname,'Tax') = $taxname
469 AND cust_tax_exempt_pkg.creditbillpkgnum IS NULL
472 SELECT 1 FROM cust_bill_pkg_tax_location
473 JOIN cust_main_county USING (taxnum)
474 WHERE cust_bill_pkg_tax_location.taxable_billpkgnum = cust_bill_pkg.billpkgnum
475 AND COALESCE(cust_main_county.taxname,'Tax') = $taxname
478 warn "\nOUTSIDE:\n$sql_outside\n" if $DEBUG;
479 my $total_outside = FS::Record->scalar_sql($sql_outside);
483 qsearch('cust_main_county', {
485 tax => { op => '>', value => 0 }
488 $taxrates{$tax->taxnum} = $tax->tax;
496 'taxrates' => \%taxrates,
497 'outside' => $total_outside,
511 # sub fetchall_array...
515 my @columns = (qw(pkgclass taxclass state county city district));
516 # taxnums, field headings, and amounts
520 # de-treeify this thing
523 my ($tree, $level) = @_;
524 if ( ref($tree) eq 'HASH' ) {
525 foreach my $k ( sort {
526 -1*($b eq '') # sort '' to the end
527 or ($a eq '') # sort '' to the end
528 or ($a <=> $b) # sort numbers as numbers
529 or ($a cmp $b) # sort alphabetics as alphabetics
532 $row_template{ $columns[$level] } = $k;
533 &{ $descend }($tree->{$k}, $level + 1);
535 # then insert the total row for the pkgclass
536 $row_template{'total'} = 1; # flag it as a total
537 &{ $descend }($self->{total}->{$k}, 1);
538 $row_template{'total'} = 0;
541 } elsif ( ref($tree) eq 'ARRAY' ) {
542 # then we've reached the bottom; elements of this array are arrayrefs
543 # of [ field, taxnums, amount ].
544 # start with the inherited location-element fields
545 my %this_row = %row_template;
547 foreach my $x (@$tree) {
549 foreach (split(',', $x->[1])) {
553 $this_row{ $x->[0] } = $x->[2];
555 # store combined taxnums
556 $this_row{taxnums} = join(',', sort { $a cmp $b } keys %taxnums);
557 # and calculate row totals
558 $this_row{sales} = sprintf('%.2f',
560 $this_row{exempt_cust} +
561 $this_row{exempt_pkg} +
562 $this_row{exempt_monthly}
564 # and give it a label
565 if ( $this_row{total} ) {
566 $this_row{label} = 'Total';
568 $this_row{label} = join(', ', grep $_,
571 $this_row{county}, # already has ' County' suffix
576 # and indicate the tax rate, if any
578 foreach (keys %taxnums) {
579 $rate ||= $self->{taxrates}->{$_};
580 if ( $rate != $self->{taxrates}->{$_} ) {
585 if ( $rate eq 'variable' ) {
586 $this_row{rate} = 'variable';
587 } elsif ( $rate > 0 ) {
588 $this_row{rate} = sprintf('%.2f', $rate);
590 push @rows, \%this_row;
594 &{ $descend }($self->{data}, 0);
596 warn "TABLE:\n".Dumper(\@rows) if $self->{opt}->{debug};
608 if ( $self->{opt}->{agentnum} ) {
609 my $agent = qsearchs('agent', { agentnum => $self->{opt}->{agentnum} });
610 $string .= $agent->agent . ' ';
612 $string .= 'Tax Report: '; # XXX localization
613 if ( $self->{opt}->{beginning} ) {
614 $string .= time2str('%h %o %Y ', $self->{opt}->{beginning});
616 $string .= 'through ';
617 if ( $self->{opt}->{ending} and $self->{opt}->{ending} < 4294967295 ) {
618 $string .= time2str('%h %o %Y', $self->{opt}->{ending});
622 $string .= ' - ' . $self->{opt}->{taxname};