FS/FS/cust_main/Billing.pm

   1 package FS::cust_main::Billing;
   2
   3 use strict;
   4 use vars qw( $conf $DEBUG $me );
   5 use Carp;
   6 use Data::Dumper;
   7 use List::Util qw( min );
   8 use FS::UID qw( dbh );
   9 use FS::Record qw( qsearch qsearchs dbdef );
  10 use FS::cust_bill;
  11 use FS::cust_bill_pkg;
  12 use FS::cust_bill_pkg_display;
  13 use FS::cust_bill_pay;
  14 use FS::cust_credit_bill;
  15 use FS::cust_pkg;
  16 use FS::cust_tax_adjustment;
  17 use FS::tax_rate;
  18 use FS::tax_rate_location;
  19 use FS::cust_bill_pkg_tax_location;
  20 use FS::cust_bill_pkg_tax_rate_location;
  21 use FS::part_event;
  22 use FS::part_event_condition;
  23
  24 # 1 is mostly method/subroutine entry and options
  25 # 2 traces progress of some operations
  26 # 3 is even more information including possibly sensitive data
  27 $DEBUG = 0;
  28 $me = '[FS::cust_main::Billing]';
  29
  30 install_callback FS::UID sub {
  31   $conf = new FS::Conf;
  32   #yes, need it for stuff below (prolly should be cached)
  33 };
  34
  35 =head1 NAME
  36
  37 FS::cust_main::Billing - Billing mixin for cust_main
  38
  39 =head1 SYNOPSIS
  40
  41 =head1 DESCRIPTION
  42
  43 These methods are available on FS::cust_main objects.
  44
  45 =head1 METHODS
  46
  47 =over 4
  48
  49 =item bill_and_collect
  50
  51 Cancels and suspends any packages due, generates bills, applies payments and
  52 credits, and applies collection events to run cards, send bills and notices,
  53 etc.
  54
  55 By default, warns on errors and continues with the next operation (but see the
  56 "fatal" flag below).
  57
  58 Options are passed as name-value pairs.  Currently available options are:
  59
  60 =over 4
  61
  62 =item time
  63
  64 Bills the customer as if it were that time.  Specified as a UNIX timestamp; see L<perlfunc/"time">).  Also see L<Time::Local> and L<Date::Parse> for conversion functions.  For example:
  65
  66  use Date::Parse;
  67  ...
  68  $cust_main->bill( 'time' => str2time('April 20th, 2001') );
  69
  70 =item invoice_time
  71
  72 Used in conjunction with the I<time> option, this option specifies the date of for the generated invoices.  Other calculations, such as whether or not to generate the invoice in the first place, are not affected.
  73
  74 =item check_freq
  75
  76 "1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq)
  77
  78 =item resetup
  79
  80 If set true, re-charges setup fees.
  81
  82 =item fatal
  83
  84 If set any errors prevent subsequent operations from continusing.  If set
  85 specifically to "return", returns the error (or false, if there is no error).
  86 Any other true value causes errors to die.
  87
  88 =item debug
  89
  90 Debugging level.  Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)
  91
  92 =item job
  93
  94 Optional FS::queue entry to receive status updates.
  95
  96 =back
  97
  98 Options are passed to the B<bill> and B<collect> methods verbatim, so all
  99 options of those methods are also available.
 100
 101 =cut
 102
 103 sub bill_and_collect {
 104   my( $self, %options ) = @_;
 105
 106   my $error;
 107
 108   #$options{actual_time} not $options{time} because freeside-daily -d is for
 109   #pre-printing invoices
 110
 111   $options{'actual_time'} ||= time;
 112   my $job = $options{'job'};
 113
 114   $job->update_statustext('0,cleaning expired packages') if $job;
 115   $error = $self->cancel_expired_pkgs( $options{actual_time} );
 116   if ( $error ) {
 117     $error = "Error expiring custnum ". $self->custnum. ": $error";
 118     if    ( $options{fatal} && $options{fatal} eq 'return' ) { return $error; }
 119     elsif ( $options{fatal}                                ) { die    $error; }
 120     else                                                     { warn   $error; }
 121   }
 122
 123   $error = $self->suspend_adjourned_pkgs( $options{actual_time} );
 124   if ( $error ) {
 125     $error = "Error adjourning custnum ". $self->custnum. ": $error";
 126     if    ( $options{fatal} && $options{fatal} eq 'return' ) { return $error; }
 127     elsif ( $options{fatal}                                ) { die    $error; }
 128     else                                                     { warn   $error; }
 129   }
 130
 131   $job->update_statustext('20,billing packages') if $job;
 132   $error = $self->bill( %options );
 133   if ( $error ) {
 134     $error = "Error billing custnum ". $self->custnum. ": $error";
 135     if    ( $options{fatal} && $options{fatal} eq 'return' ) { return $error; }
 136     elsif ( $options{fatal}                                ) { die    $error; }
 137     else                                                     { warn   $error; }
 138   }
 139
 140   $job->update_statustext('50,applying payments and credits') if $job;
 141   $error = $self->apply_payments_and_credits;
 142   if ( $error ) {
 143     $error = "Error applying custnum ". $self->custnum. ": $error";
 144     if    ( $options{fatal} && $options{fatal} eq 'return' ) { return $error; }
 145     elsif ( $options{fatal}                                ) { die    $error; }
 146     else                                                     { warn   $error; }
 147   }
 148
 149   $job->update_statustext('70,running collection events') if $job;
 150   unless ( $conf->exists('cancelled_cust-noevents')
 151            && ! $self->num_ncancelled_pkgs
 152   ) {
 153     $error = $self->collect( %options );
 154     if ( $error ) {
 155       $error = "Error collecting custnum ". $self->custnum. ": $error";
 156       if    ($options{fatal} && $options{fatal} eq 'return') { return $error; }
 157       elsif ($options{fatal}                               ) { die    $error; }
 158       else                                                   { warn   $error; }
 159     }
 160   }
 161   $job->update_statustext('100,finished') if $job;
 162
 163   '';
 164
 165 }
 166
 167 sub cancel_expired_pkgs {
 168   my ( $self, $time, %options ) = @_;
 169
 170   my @cancel_pkgs = $self->ncancelled_pkgs( {
 171     'extra_sql' => " AND expire IS NOT NULL AND expire > 0 AND expire <= $time "
 172   } );
 173
 174   my @errors = ();
 175
 176   foreach my $cust_pkg ( @cancel_pkgs ) {
 177     my $cpr = $cust_pkg->last_cust_pkg_reason('expire');
 178     my $error = $cust_pkg->cancel($cpr ? ( 'reason'        => $cpr->reasonnum,
 179                                            'reason_otaker' => $cpr->otaker
 180                                          )
 181                                        : ()
 182                                  );
 183     push @errors, 'pkgnum '.$cust_pkg->pkgnum.": $error" if $error;
 184   }
 185
 186   scalar(@errors) ? join(' / ', @errors) : '';
 187
 188 }
 189
 190 sub suspend_adjourned_pkgs {
 191   my ( $self, $time, %options ) = @_;
 192
 193   my @susp_pkgs = $self->ncancelled_pkgs( {
 194     'extra_sql' =>
 195       " AND ( susp IS NULL OR susp = 0 )
 196         AND (    ( bill    IS NOT NULL AND bill    != 0 AND bill    <  $time )
 197               OR ( adjourn IS NOT NULL AND adjourn != 0 AND adjourn <= $time )
 198             )
 199       ",
 200   } );
 201
 202   #only because there's no SQL test for is_prepaid :/
 203   @susp_pkgs =
 204     grep {     (    $_->part_pkg->is_prepaid
 205                  && $_->bill
 206                  && $_->bill < $time
 207                )
 208             || (    $_->adjourn
 209                  && $_->adjourn <= $time
 210                )
 211
 212          }
 213          @susp_pkgs;
 214
 215   my @errors = ();
 216
 217   foreach my $cust_pkg ( @susp_pkgs ) {
 218     my $cpr = $cust_pkg->last_cust_pkg_reason('adjourn')
 219       if ($cust_pkg->adjourn && $cust_pkg->adjourn < $^T);
 220     my $error = $cust_pkg->suspend($cpr ? ( 'reason' => $cpr->reasonnum,
 221                                             'reason_otaker' => $cpr->otaker
 222                                           )
 223                                         : ()
 224                                   );
 225     push @errors, 'pkgnum '.$cust_pkg->pkgnum.": $error" if $error;
 226   }
 227
 228   scalar(@errors) ? join(' / ', @errors) : '';
 229
 230 }
 231
 232 =item bill OPTIONS
 233
 234 Generates invoices (see L<FS::cust_bill>) for this customer.  Usually used in
 235 conjunction with the collect method by calling B<bill_and_collect>.
 236
 237 If there is an error, returns the error, otherwise returns false.
 238
 239 Options are passed as name-value pairs.  Currently available options are:
 240
 241 =over 4
 242
 243 =item resetup
 244
 245 If set true, re-charges setup fees.
 246
 247 =item recurring_only
 248
 249 If set true then only bill recurring charges, not setup, usage, one time
 250 charges, etc.
 251
 252 =item freq_override
 253
 254 If set, then override the normal frequency and look for a part_pkg_discount
 255 to take at that frequency.
 256
 257 =item time
 258
 259 Bills the customer as if it were that time.  Specified as a UNIX timestamp; see L<perlfunc/"time">).  Also see L<Time::Local> and L<Date::Parse> for conversion functions.  For example:
 260
 261  use Date::Parse;
 262  ...
 263  $cust_main->bill( 'time' => str2time('April 20th, 2001') );
 264
 265 =item pkg_list
 266
 267 An array ref of specific packages (objects) to attempt billing, instead trying all of them.
 268
 269  $cust_main->bill( pkg_list => [$pkg1, $pkg2] );
 270
 271 =item not_pkgpart
 272
 273 A hashref of pkgparts to exclude from this billing run (can also be specified as a comma-separated scalar).
 274
 275 =item invoice_time
 276
 277 Used in conjunction with the I<time> option, this option specifies the date of for the generated invoices.  Other calculations, such as whether or not to generate the invoice in the first place, are not affected.
 278
 279 =item cancel
 280
 281 This boolean value informs the us that the package is being cancelled.  This
 282 typically might mean not charging the normal recurring fee but only usage
 283 fees since the last billing. Setup charges may be charged.  Not all package
 284 plans support this feature (they tend to charge 0).
 285
 286 =item no_usage_reset
 287
 288 Prevent the resetting of usage limits during this call.
 289
 290 =item no_commit
 291
 292 Do not save the generated bill in the database.  Useful with return_bill
 293
 294 =item return_bill
 295
 296 A list reference on which the generated bill(s) will be returned.
 297
 298 =item invoice_terms
 299
 300 Optional terms to be printed on this invoice.  Otherwise, customer-specific
 301 terms or the default terms are used.
 302
 303 =back
 304
 305 =cut
 306
 307 sub bill {
 308   my( $self, %options ) = @_;
 309
 310   return '' if $self->payby eq 'COMP';
 311
 312   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
 313
 314   warn "$me bill customer ". $self->custnum. "\n"
 315     if $DEBUG;
 316
 317   my $time = $options{'time'} || time;
 318   my $invoice_time = $options{'invoice_time'} || $time;
 319
 320   $options{'not_pkgpart'} ||= {};
 321   $options{'not_pkgpart'} = { map { $_ => 1 }
 322                                   split(/\s*,\s*/, $options{'not_pkgpart'})
 323                             }
 324     unless ref($options{'not_pkgpart'});
 325
 326   local $SIG{HUP} = 'IGNORE';
 327   local $SIG{INT} = 'IGNORE';
 328   local $SIG{QUIT} = 'IGNORE';
 329   local $SIG{TERM} = 'IGNORE';
 330   local $SIG{TSTP} = 'IGNORE';
 331   local $SIG{PIPE} = 'IGNORE';
 332
 333   my $oldAutoCommit = $FS::UID::AutoCommit;
 334   local $FS::UID::AutoCommit = 0;
 335   my $dbh = dbh;
 336
 337   warn "$me acquiring lock on customer ". $self->custnum. "\n"
 338     if $DEBUG;
 339
 340   $self->select_for_update; #mutex
 341
 342   warn "$me running pre-bill events for customer ". $self->custnum. "\n"
 343     if $DEBUG;
 344
 345   my $error = $self->do_cust_event(
 346     'debug'      => ( $options{'debug'} || 0 ),
 347     'time'       => $invoice_time,
 348     'check_freq' => $options{'check_freq'},
 349     'stage'      => 'pre-bill',
 350   )
 351     unless $options{no_commit};
 352   if ( $error ) {
 353     $dbh->rollback if $oldAutoCommit && !$options{no_commit};
 354     return $error;
 355   }
 356
 357   warn "$me done running pre-bill events for customer ". $self->custnum. "\n"
 358     if $DEBUG;
 359
 360   #keep auto-charge and non-auto-charge line items separate
 361   my @passes = ( '', 'no_auto' );
 362
 363   my %cust_bill_pkg = map { $_ => [] } @passes;
 364
 365   ###
 366   # find the packages which are due for billing, find out how much they are
 367   # & generate invoice database.
 368   ###
 369
 370   my %total_setup   = map { my $z = 0; $_ => \$z; } @passes;
 371   my %total_recur   = map { my $z = 0; $_ => \$z; } @passes;
 372
 373   my %taxlisthash = map { $_ => {} } @passes;
 374
 375   my @precommit_hooks = ();
 376
 377   $options{'pkg_list'} ||= [ $self->ncancelled_pkgs ];  #param checks?
 378   foreach my $cust_pkg ( @{ $options{'pkg_list'} } ) {
 379
 380     next if $options{'not_pkgpart'}->{$cust_pkg->pkgpart};
 381
 382     warn "  bill package ". $cust_pkg->pkgnum. "\n" if $DEBUG > 1;
 383
 384     #? to avoid use of uninitialized value errors... ?
 385     $cust_pkg->setfield('bill', '')
 386       unless defined($cust_pkg->bill);
 387
 388     #my $part_pkg = $cust_pkg->part_pkg;
 389
 390     my $real_pkgpart = $cust_pkg->pkgpart;
 391     my %hash = $cust_pkg->hash;
 392
 393     # we could implement this bit as FS::part_pkg::has_hidden, but we already
 394     # suffer from performance issues
 395     $options{has_hidden} = 0;
 396     my @part_pkg = $cust_pkg->part_pkg->self_and_bill_linked;
 397     $options{has_hidden} = 1 if ($part_pkg[1] && $part_pkg[1]->hidden);
 398
 399     foreach my $part_pkg ( @part_pkg ) {
 400
 401       $cust_pkg->set($_, $hash{$_}) foreach qw ( setup last_bill bill );
 402
 403       my $pass = ($cust_pkg->no_auto || $part_pkg->no_auto) ? 'no_auto' : '';
 404
 405       my $error =
 406         $self->_make_lines( 'part_pkg'            => $part_pkg,
 407                             'cust_pkg'            => $cust_pkg,
 408                             'precommit_hooks'     => \@precommit_hooks,
 409                             'line_items'          => $cust_bill_pkg{$pass},
 410                             'setup'               => $total_setup{$pass},
 411                             'recur'               => $total_recur{$pass},
 412                             'tax_matrix'          => $taxlisthash{$pass},
 413                             'time'                => $time,
 414                             'real_pkgpart'        => $real_pkgpart,
 415                             'options'             => \%options,
 416                           );
 417       if ($error) {
 418         $dbh->rollback if $oldAutoCommit && !$options{no_commit};
 419         return $error;
 420       }
 421
 422     } #foreach my $part_pkg
 423
 424   } #foreach my $cust_pkg
 425
 426   #if the customer isn't on an automatic payby, everything can go on a single
 427   #invoice anyway?
 428   #if ( $cust_main->payby !~ /^(CARD|CHEK)$/ ) {
 429     #merge everything into one list
 430   #}
 431
 432   foreach my $pass (@passes) { # keys %cust_bill_pkg ) {
 433
 434     my @cust_bill_pkg = _omit_zero_value_bundles(@{ $cust_bill_pkg{$pass} });
 435
 436     next unless @cust_bill_pkg; #don't create an invoice w/o line items
 437
 438     warn "$me billing pass $pass\n"
 439            #.Dumper(\@cust_bill_pkg)."\n"
 440       if $DEBUG > 2;
 441
 442     if ( scalar( grep { $_->recur && $_->recur > 0 } @cust_bill_pkg) ||
 443            !$conf->exists('postal_invoice-recurring_only')
 444        )
 445     {
 446
 447       my $postal_pkg = $self->charge_postal_fee();
 448       if ( $postal_pkg && !ref( $postal_pkg ) ) {
 449
 450         $dbh->rollback if $oldAutoCommit && !$options{no_commit};
 451         return "can't charge postal invoice fee for customer ".
 452           $self->custnum. ": $postal_pkg";
 453
 454       } elsif ( $postal_pkg ) {
 455
 456         my $real_pkgpart = $postal_pkg->pkgpart;
 457         # we could implement this bit as FS::part_pkg::has_hidden, but we already
 458         # suffer from performance issues
 459         $options{has_hidden} = 0;
 460         my @part_pkg = $postal_pkg->part_pkg->self_and_bill_linked;
 461         $options{has_hidden} = 1 if ($part_pkg[1] && $part_pkg[1]->hidden);
 462
 463         foreach my $part_pkg ( @part_pkg ) {
 464           my %postal_options = %options;
 465           delete $postal_options{cancel};
 466           my $error =
 467             $self->_make_lines( 'part_pkg'            => $part_pkg,
 468                                 'cust_pkg'            => $postal_pkg,
 469                                 'precommit_hooks'     => \@precommit_hooks,
 470                                 'line_items'          => \@cust_bill_pkg,
 471                                 'setup'               => $total_setup{$pass},
 472                                 'recur'               => $total_recur{$pass},
 473                                 'tax_matrix'          => $taxlisthash{$pass},
 474                                 'time'                => $time,
 475                                 'real_pkgpart'        => $real_pkgpart,
 476                                 'options'             => \%postal_options,
 477                               );
 478           if ($error) {
 479             $dbh->rollback if $oldAutoCommit && !$options{no_commit};
 480             return $error;
 481           }
 482         }
 483
 484         # it's silly to have a zero value postal_pkg, but....
 485         @cust_bill_pkg = _omit_zero_value_bundles(@cust_bill_pkg);
 486
 487       }
 488
 489     }
 490
 491     my $listref_or_error =
 492       $self->calculate_taxes( \@cust_bill_pkg, $taxlisthash{$pass}, $invoice_time);
 493
 494     unless ( ref( $listref_or_error ) ) {
 495       $dbh->rollback if $oldAutoCommit && !$options{no_commit};
 496       return $listref_or_error;
 497     }
 498
 499     foreach my $taxline ( @$listref_or_error ) {
 500       ${ $total_setup{$pass} } =
 501         sprintf('%.2f', ${ $total_setup{$pass} } + $taxline->setup );
 502       push @cust_bill_pkg, $taxline;
 503     }
 504
 505     #add tax adjustments
 506     warn "adding tax adjustments...\n" if $DEBUG > 2;
 507     foreach my $cust_tax_adjustment (
 508       qsearch('cust_tax_adjustment', { 'custnum'    => $self->custnum,
 509                                        'billpkgnum' => '',
 510                                      }
 511              )
 512     ) {
 513
 514       my $tax = sprintf('%.2f', $cust_tax_adjustment->amount );
 515
 516       my $itemdesc = $cust_tax_adjustment->taxname;
 517       $itemdesc = '' if $itemdesc eq 'Tax';
 518
 519       push @cust_bill_pkg, new FS::cust_bill_pkg {
 520         'pkgnum'      => 0,
 521         'setup'       => $tax,
 522         'recur'       => 0,
 523         'sdate'       => '',
 524         'edate'       => '',
 525         'itemdesc'    => $itemdesc,
 526         'itemcomment' => $cust_tax_adjustment->comment,
 527         'cust_tax_adjustment' => $cust_tax_adjustment,
 528         #'cust_bill_pkg_tax_location' => \@cust_bill_pkg_tax_location,
 529       };
 530
 531     }
 532
 533     my $charged = sprintf('%.2f', ${ $total_setup{$pass} } + ${ $total_recur{$pass} } );
 534
 535     my @cust_bill = $self->cust_bill;
 536     my $balance = $self->balance;
 537     my $previous_balance = scalar(@cust_bill)
 538                              ? ( $cust_bill[$#cust_bill]->billing_balance || 0 )
 539                              : 0;
 540
 541     $previous_balance += $cust_bill[$#cust_bill]->charged
 542       if scalar(@cust_bill);
 543     #my $balance_adjustments =
 544     #  sprintf('%.2f', $balance - $prior_prior_balance - $prior_charged);
 545
 546     warn "creating the new invoice\n" if $DEBUG;
 547     #create the new invoice
 548     my $cust_bill = new FS::cust_bill ( {
 549       'custnum'             => $self->custnum,
 550       '_date'               => ( $invoice_time ),
 551       'charged'             => $charged,
 552       'billing_balance'     => $balance,
 553       'previous_balance'    => $previous_balance,
 554       'invoice_terms'       => $options{'invoice_terms'},
 555       'cust_bill_pkg'       => \@cust_bill_pkg,
 556     } );
 557     $error = $cust_bill->insert unless $options{no_commit};
 558     if ( $error ) {
 559       $dbh->rollback if $oldAutoCommit && !$options{no_commit};
 560       return "can't create invoice for customer #". $self->custnum. ": $error";
 561     }
 562     push @{$options{return_bill}}, $cust_bill if $options{return_bill};
 563
 564   } #foreach my $pass ( keys %cust_bill_pkg )
 565
 566   foreach my $hook ( @precommit_hooks ) {
 567     eval {
 568       &{$hook}; #($self) ?
 569     } unless $options{no_commit};
 570     if ( $@ ) {
 571       $dbh->rollback if $oldAutoCommit && !$options{no_commit};
 572       return "$@ running precommit hook $hook\n";
 573     }
 574   }
 575
 576   $dbh->commit or die $dbh->errstr if $oldAutoCommit && !$options{no_commit};
 577
 578   ''; #no error
 579 }
 580
 581 #discard bundled packages of 0 value
 582 sub _omit_zero_value_bundles {
 583
 584   my @cust_bill_pkg = ();
 585   my @cust_bill_pkg_bundle = ();
 586   my $sum = 0;
 587
 588   foreach my $cust_bill_pkg ( @_ ) {
 589     if (scalar(@cust_bill_pkg_bundle) && !$cust_bill_pkg->pkgpart_override) {
 590       push @cust_bill_pkg, @cust_bill_pkg_bundle if $sum > 0;
 591       @cust_bill_pkg_bundle = ();
 592       $sum = 0;
 593     }
 594     $sum += $cust_bill_pkg->setup + $cust_bill_pkg->recur;
 595     push @cust_bill_pkg_bundle, $cust_bill_pkg;
 596   }
 597   push @cust_bill_pkg, @cust_bill_pkg_bundle if $sum > 0;
 598
 599   (@cust_bill_pkg);
 600
 601 }
 602
 603 =item calculate_taxes LINEITEMREF TAXHASHREF INVOICE_TIME
 604
 605 This is a weird one.  Perhaps it should not even be exposed.
 606
 607 Generates tax line items (see L<FS::cust_bill_pkg>) for this customer.
 608 Usually used internally by bill method B<bill>.
 609
 610 If there is an error, returns the error, otherwise returns reference to a
 611 list of line items suitable for insertion.
 612
 613 =over 4
 614
 615 =item LINEITEMREF
 616
 617 An array ref of the line items being billed.
 618
 619 =item TAXHASHREF
 620
 621 A strange beast.  The keys to this hash are internal identifiers consisting
 622 of the name of the tax object type, a space, and its unique identifier ( e.g.
 623  'cust_main_county 23' ).  The values of the hash are listrefs.  The first
 624 item in the list is the tax object.  The remaining items are either line
 625 items or floating point values (currency amounts).
 626
 627 The taxes are calculated on this entity.  Calculated exemption records are
 628 transferred to the LINEITEMREF items on the assumption that they are related.
 629
 630 Read the source.
 631
 632 =item INVOICE_TIME
 633
 634 This specifies the date appearing on the associated invoice.  Some
 635 jurisdictions (i.e. Texas) have tax exemptions which are date sensitive.
 636
 637 =back
 638
 639 =cut
 640
 641 sub calculate_taxes {
 642   my ($self, $cust_bill_pkg, $taxlisthash, $invoice_time) = @_;
 643
 644   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
 645
 646   warn "$me calculate_taxes\n"
 647        #.Dumper($self, $cust_bill_pkg, $taxlisthash, $invoice_time). "\n"
 648     if $DEBUG > 2;
 649
 650   my @tax_line_items = ();
 651
 652   # keys are tax names (as printed on invoices / itemdesc )
 653   # values are listrefs of taxlisthash keys (internal identifiers)
 654   my %taxname = ();
 655
 656   # keys are taxlisthash keys (internal identifiers)
 657   # values are (cumulative) amounts
 658   my %tax = ();
 659
 660   # keys are taxlisthash keys (internal identifiers)
 661   # values are listrefs of cust_bill_pkg_tax_location hashrefs
 662   my %tax_location = ();
 663
 664   # keys are taxlisthash keys (internal identifiers)
 665   # values are listrefs of cust_bill_pkg_tax_rate_location hashrefs
 666   my %tax_rate_location = ();
 667
 668   foreach my $tax ( keys %$taxlisthash ) {
 669     my $tax_object = shift @{ $taxlisthash->{$tax} };
 670     warn "found ". $tax_object->taxname. " as $tax\n" if $DEBUG > 2;
 671     warn " ". join('/', @{ $taxlisthash->{$tax} } ). "\n" if $DEBUG > 2;
 672     my $hashref_or_error =
 673       $tax_object->taxline( $taxlisthash->{$tax},
 674                             'custnum'      => $self->custnum,
 675                             'invoice_time' => $invoice_time
 676                           );
 677     return $hashref_or_error unless ref($hashref_or_error);
 678
 679     unshift @{ $taxlisthash->{$tax} }, $tax_object;
 680
 681     my $name   = $hashref_or_error->{'name'};
 682     my $amount = $hashref_or_error->{'amount'};
 683
 684     #warn "adding $amount as $name\n";
 685     $taxname{ $name } ||= [];
 686     push @{ $taxname{ $name } }, $tax;
 687
 688     $tax{ $tax } += $amount;
 689
 690     $tax_location{ $tax } ||= [];
 691     if ( $tax_object->get('pkgnum') || $tax_object->get('locationnum') ) {
 692       push @{ $tax_location{ $tax }  },
 693         {
 694           'taxnum'      => $tax_object->taxnum,
 695           'taxtype'     => ref($tax_object),
 696           'pkgnum'      => $tax_object->get('pkgnum'),
 697           'locationnum' => $tax_object->get('locationnum'),
 698           'amount'      => sprintf('%.2f', $amount ),
 699         };
 700     }
 701
 702     $tax_rate_location{ $tax } ||= [];
 703     if ( ref($tax_object) eq 'FS::tax_rate' ) {
 704       my $taxratelocationnum =
 705         $tax_object->tax_rate_location->taxratelocationnum;
 706       push @{ $tax_rate_location{ $tax }  },
 707         {
 708           'taxnum'             => $tax_object->taxnum,
 709           'taxtype'            => ref($tax_object),
 710           'amount'             => sprintf('%.2f', $amount ),
 711           'locationtaxid'      => $tax_object->location,
 712           'taxratelocationnum' => $taxratelocationnum,
 713         };
 714     }
 715
 716   }
 717
 718   #move the cust_tax_exempt_pkg records to the cust_bill_pkgs we will commit
 719   my %packagemap = map { $_->pkgnum => $_ } @$cust_bill_pkg;
 720   foreach my $tax ( keys %$taxlisthash ) {
 721     foreach ( @{ $taxlisthash->{$tax} }[1 ... scalar(@{ $taxlisthash->{$tax} })] ) {
 722       next unless ref($_) eq 'FS::cust_bill_pkg';
 723       push @{ $packagemap{$_->pkgnum}->_cust_tax_exempt_pkg },
 724         splice( @{ $_->_cust_tax_exempt_pkg } );
 725     }
 726   }
 727
 728   #consolidate and create tax line items
 729   warn "consolidating and generating...\n" if $DEBUG > 2;
 730   foreach my $taxname ( keys %taxname ) {
 731     my $tax = 0;
 732     my %seen = ();
 733     my @cust_bill_pkg_tax_location = ();
 734     my @cust_bill_pkg_tax_rate_location = ();
 735     warn "adding $taxname\n" if $DEBUG > 1;
 736     foreach my $taxitem ( @{ $taxname{$taxname} } ) {
 737       next if $seen{$taxitem}++;
 738       warn "adding $tax{$taxitem}\n" if $DEBUG > 1;
 739       $tax += $tax{$taxitem};
 740       push @cust_bill_pkg_tax_location,
 741         map { new FS::cust_bill_pkg_tax_location $_ }
 742             @{ $tax_location{ $taxitem } };
 743       push @cust_bill_pkg_tax_rate_location,
 744         map { new FS::cust_bill_pkg_tax_rate_location $_ }
 745             @{ $tax_rate_location{ $taxitem } };
 746     }
 747     next unless $tax;
 748
 749     $tax = sprintf('%.2f', $tax );
 750
 751     my $pkg_category = qsearchs( 'pkg_category', { 'categoryname' => $taxname,
 752                                                    'disabled'     => '',
 753                                                  },
 754                                );
 755
 756     my @display = ();
 757     if ( $pkg_category and
 758          $conf->config('invoice_latexsummary') ||
 759          $conf->config('invoice_htmlsummary')
 760        )
 761     {
 762
 763       my %hash = (  'section' => $pkg_category->categoryname );
 764       push @display, new FS::cust_bill_pkg_display { type => 'S', %hash };
 765
 766     }
 767
 768     push @tax_line_items, new FS::cust_bill_pkg {
 769       'pkgnum'   => 0,
 770       'setup'    => $tax,
 771       'recur'    => 0,
 772       'sdate'    => '',
 773       'edate'    => '',
 774       'itemdesc' => $taxname,
 775       'display'  => \@display,
 776       'cust_bill_pkg_tax_location' => \@cust_bill_pkg_tax_location,
 777       'cust_bill_pkg_tax_rate_location' => \@cust_bill_pkg_tax_rate_location,
 778     };
 779
 780   }
 781
 782   \@tax_line_items;
 783 }
 784
 785 sub _make_lines {
 786   my ($self, %params) = @_;
 787
 788   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
 789
 790   my $part_pkg = $params{part_pkg} or die "no part_pkg specified";
 791   my $cust_pkg = $params{cust_pkg} or die "no cust_pkg specified";
 792   my $precommit_hooks = $params{precommit_hooks} or die "no package specified";
 793   my $cust_bill_pkgs = $params{line_items} or die "no line buffer specified";
 794   my $total_setup = $params{setup} or die "no setup accumulator specified";
 795   my $total_recur = $params{recur} or die "no recur accumulator specified";
 796   my $taxlisthash = $params{tax_matrix} or die "no tax accumulator specified";
 797   my $time = $params{'time'} or die "no time specified";
 798   my (%options) = %{$params{options}};
 799
 800   my $dbh = dbh;
 801   my $real_pkgpart = $params{real_pkgpart};
 802   my %hash = $cust_pkg->hash;
 803   my $old_cust_pkg = new FS::cust_pkg \%hash;
 804
 805   my @details = ();
 806   my @discounts = ();
 807   my $lineitems = 0;
 808
 809   $cust_pkg->pkgpart($part_pkg->pkgpart);
 810
 811   ###
 812   # bill setup
 813   ###
 814
 815   my $setup = 0;
 816   my $unitsetup = 0;
 817   if ( $options{'resetup'}
 818        || ( ! $cust_pkg->setup
 819             && ( ! $cust_pkg->start_date
 820                  || $cust_pkg->start_date <= $time
 821                )
 822             && ( ! $conf->exists('disable_setup_suspended_pkgs')
 823                  || ( $conf->exists('disable_setup_suspended_pkgs') &&
 824                       ! $cust_pkg->getfield('susp')
 825                     )
 826                )
 827           )
 828         and !$options{recurring_only}
 829     )
 830   {
 831
 832     warn "    bill setup\n" if $DEBUG > 1;
 833     $lineitems++;
 834
 835     $setup = eval { $cust_pkg->calc_setup( $time, \@details ) };
 836     return "$@ running calc_setup for $cust_pkg\n"
 837       if $@;
 838
 839     $unitsetup = $cust_pkg->part_pkg->unit_setup || $setup; #XXX uuh
 840
 841     $cust_pkg->setfield('setup', $time)
 842       unless $cust_pkg->setup;
 843           #do need it, but it won't get written to the db
 844           #|| $cust_pkg->pkgpart != $real_pkgpart;
 845
 846     $cust_pkg->setfield('start_date', '')
 847       if $cust_pkg->start_date;
 848
 849   }
 850
 851   ###
 852   # bill recurring fee
 853   ###
 854
 855   #XXX unit stuff here too
 856   my $recur = 0;
 857   my $unitrecur = 0;
 858   my $sdate;
 859   if (     ! $cust_pkg->start_date
 860        and ( ! $cust_pkg->susp || $part_pkg->option('suspend_bill') )
 861        and
 862             ( $part_pkg->freq ne '0' && ( $cust_pkg->bill || 0 ) <= $time )
 863          || ( $part_pkg->plan eq 'voip_cdr'
 864                && $part_pkg->option('bill_every_call')
 865             )
 866          || $options{cancel}
 867   ) {
 868
 869     # XXX should this be a package event?  probably.  events are called
 870     # at collection time at the moment, though...
 871     $part_pkg->reset_usage($cust_pkg, 'debug'=>$DEBUG)
 872       if $part_pkg->can('reset_usage') && !$options{'no_usage_reset'};
 873       #don't want to reset usage just cause we want a line item??
 874       #&& $part_pkg->pkgpart == $real_pkgpart;
 875
 876     warn "    bill recur\n" if $DEBUG > 1;
 877     $lineitems++;
 878
 879     # XXX shared with $recur_prog
 880     $sdate = ( $options{cancel} ? $cust_pkg->last_bill : $cust_pkg->bill )
 881              || $cust_pkg->setup
 882              || $time;
 883
 884     #over two params!  lets at least switch to a hashref for the rest...
 885     my $increment_next_bill = ( $part_pkg->freq ne '0'
 886                                 && ( $cust_pkg->getfield('bill') || 0 ) <= $time
 887                                 && !$options{cancel}
 888                               );
 889     my %param = ( 'precommit_hooks'     => $precommit_hooks,
 890                   'increment_next_bill' => $increment_next_bill,
 891                   'discounts'           => \@discounts,
 892                   'real_pkgpart'        => $real_pkgpart,
 893                   'freq_override'       => $options{freq_override} || '',
 894                 );
 895
 896     my $method = $options{cancel} ? 'calc_cancel' : 'calc_recur';
 897
 898     # There may be some part_pkg for which this is wrong.  Only those
 899     # which can_discount are supported.
 900
 901     $recur = eval { $cust_pkg->$method( \$sdate, \@details, \%param ) };
 902     return "$@ running $method for $cust_pkg\n"
 903       if ( $@ );
 904
 905     if ( $increment_next_bill ) {
 906
 907       my $next_bill = $part_pkg->add_freq($sdate, $options{freq_override} || 0);
 908       return "unparsable frequency: ". $part_pkg->freq
 909         if $next_bill == -1;
 910
 911       #pro-rating magic - if $recur_prog fiddled $sdate, want to use that
 912       # only for figuring next bill date, nothing else, so, reset $sdate again
 913       # here
 914       $sdate = $cust_pkg->bill || $cust_pkg->setup || $time;
 915       #no need, its in $hash{last_bill}# my $last_bill = $cust_pkg->last_bill;
 916       $cust_pkg->last_bill($sdate);
 917
 918       $cust_pkg->setfield('bill', $next_bill );
 919
 920     }
 921
 922   }
 923
 924   warn "\$setup is undefined" unless defined($setup);
 925   warn "\$recur is undefined" unless defined($recur);
 926   warn "\$cust_pkg->bill is undefined" unless defined($cust_pkg->bill);
 927
 928   ###
 929   # If there's line items, create em cust_bill_pkg records
 930   # If $cust_pkg has been modified, update it (if we're a real pkgpart)
 931   ###
 932
 933   if ( $lineitems ) {
 934
 935     if ( $cust_pkg->modified && $cust_pkg->pkgpart == $real_pkgpart ) {
 936       # hmm.. and if just the options are modified in some weird price plan?
 937
 938       warn "  package ". $cust_pkg->pkgnum. " modified; updating\n"
 939         if $DEBUG >1;
 940
 941       my $error = $cust_pkg->replace( $old_cust_pkg,
 942                                       'options' => { $cust_pkg->options },
 943                                     )
 944         unless $options{no_commit};
 945       return "Error modifying pkgnum ". $cust_pkg->pkgnum. ": $error"
 946         if $error; #just in case
 947     }
 948
 949     $setup = sprintf( "%.2f", $setup );
 950     $recur = sprintf( "%.2f", $recur );
 951     if ( $setup < 0 && ! $conf->exists('allow_negative_charges') ) {
 952       return "negative setup $setup for pkgnum ". $cust_pkg->pkgnum;
 953     }
 954     if ( $recur < 0 && ! $conf->exists('allow_negative_charges') ) {
 955       return "negative recur $recur for pkgnum ". $cust_pkg->pkgnum;
 956     }
 957
 958     if ( $setup != 0 ||
 959          $recur != 0 ||
 960          !$part_pkg->hidden && $options{has_hidden} ) #include some $0 lines
 961     {
 962
 963       warn "    charges (setup=$setup, recur=$recur); adding line items\n"
 964         if $DEBUG > 1;
 965
 966       my @cust_pkg_detail = map { $_->detail } $cust_pkg->cust_pkg_detail('I');
 967       if ( $DEBUG > 1 ) {
 968         warn "      adding customer package invoice detail: $_\n"
 969           foreach @cust_pkg_detail;
 970       }
 971       push @details, @cust_pkg_detail;
 972
 973       my $cust_bill_pkg = new FS::cust_bill_pkg {
 974         'pkgnum'    => $cust_pkg->pkgnum,
 975         'setup'     => $setup,
 976         'unitsetup' => $unitsetup,
 977         'recur'     => $recur,
 978         'unitrecur' => $unitrecur,
 979         'quantity'  => $cust_pkg->quantity,
 980         'details'   => \@details,
 981         'discounts' => \@discounts,
 982         'hidden'    => $part_pkg->hidden,
 983         'freq'      => $part_pkg->freq,
 984       };
 985
 986       if ( $part_pkg->option('recur_temporality', 1) eq 'preceding' ) {
 987         $cust_bill_pkg->sdate( $hash{last_bill} );
 988         $cust_bill_pkg->edate( $sdate - 86399   ); #60s*60m*24h-1
 989         $cust_bill_pkg->edate( $time ) if $options{cancel};
 990       } else { #if ( $part_pkg->option('recur_temporality', 1) eq 'upcoming' ) {
 991         $cust_bill_pkg->sdate( $sdate );
 992         $cust_bill_pkg->edate( $cust_pkg->bill );
 993         #$cust_bill_pkg->edate( $time ) if $options{cancel};
 994       }
 995
 996       $cust_bill_pkg->pkgpart_override($part_pkg->pkgpart)
 997         unless $part_pkg->pkgpart == $real_pkgpart;
 998
 999       $$total_setup += $setup;
1000       $$total_recur += $recur;
1001
1002       ###
1003       # handle taxes
1004       ###
1005
1006       my $error =
1007         $self->_handle_taxes($part_pkg, $taxlisthash, $cust_bill_pkg, $cust_pkg, $options{invoice_time}, $real_pkgpart, \%options);
1008       return $error if $error;
1009
1010       push @$cust_bill_pkgs, $cust_bill_pkg;
1011
1012     } #if $setup != 0 || $recur != 0
1013
1014   } #if $line_items
1015
1016   '';
1017
1018 }
1019
1020 sub _handle_taxes {
1021   my $self = shift;
1022   my $part_pkg = shift;
1023   my $taxlisthash = shift;
1024   my $cust_bill_pkg = shift;
1025   my $cust_pkg = shift;
1026   my $invoice_time = shift;
1027   my $real_pkgpart = shift;
1028   my $options = shift;
1029
1030   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
1031
1032   my %cust_bill_pkg = ();
1033   my %taxes = ();
1034
1035   my @classes;
1036   #push @classes, $cust_bill_pkg->usage_classes if $cust_bill_pkg->type eq 'U';
1037   push @classes, $cust_bill_pkg->usage_classes if $cust_bill_pkg->usage;
1038   push @classes, 'setup' if ($cust_bill_pkg->setup && !$options->{cancel});
1039   push @classes, 'recur' if ($cust_bill_pkg->recur && !$options->{cancel});
1040
1041   if ( $self->tax !~ /Y/i && $self->payby ne 'COMP' ) {
1042
1043     if ( $conf->exists('enable_taxproducts')
1044          && ( scalar($part_pkg->part_pkg_taxoverride)
1045               || $part_pkg->has_taxproduct
1046             )
1047        )
1048     {
1049
1050       foreach my $class (@classes) {
1051         my $err_or_ref = $self->_gather_taxes( $part_pkg, $class, $cust_pkg );
1052         return $err_or_ref unless ref($err_or_ref);
1053         $taxes{$class} = $err_or_ref;
1054       }
1055
1056       unless (exists $taxes{''}) {
1057         my $err_or_ref = $self->_gather_taxes( $part_pkg, '', $cust_pkg );
1058         return $err_or_ref unless ref($err_or_ref);
1059         $taxes{''} = $err_or_ref;
1060       }
1061
1062     } else {
1063
1064       my @loc_keys = qw( city county state country );
1065       my %taxhash;
1066       if ( $conf->exists('tax-pkg_address') && $cust_pkg->locationnum ) {
1067         my $cust_location = $cust_pkg->cust_location;
1068         %taxhash = map { $_ => $cust_location->$_()    } @loc_keys;
1069       } else {
1070         my $prefix =
1071           ( $conf->exists('tax-ship_address') && length($self->ship_last) )
1072           ? 'ship_'
1073           : '';
1074         %taxhash = map { $_ => $self->get("$prefix$_") } @loc_keys;
1075       }
1076
1077       $taxhash{'taxclass'} = $part_pkg->taxclass;
1078
1079       my @taxes = ();
1080       my %taxhash_elim = %taxhash;
1081       my @elim = qw( city county state );
1082       do {
1083
1084         #first try a match with taxclass
1085         @taxes = qsearch( 'cust_main_county', \%taxhash_elim );
1086
1087         if ( !scalar(@taxes) && $taxhash_elim{'taxclass'} ) {
1088           #then try a match without taxclass
1089           my %no_taxclass = %taxhash_elim;
1090           $no_taxclass{ 'taxclass' } = '';
1091           @taxes = qsearch( 'cust_main_county', \%no_taxclass );
1092         }
1093
1094         $taxhash_elim{ shift(@elim) } = '';
1095
1096       } while ( !scalar(@taxes) && scalar(@elim) );
1097
1098       @taxes = grep { ! $_->taxname or ! $self->tax_exemption($_->taxname) }
1099                     @taxes
1100         if $self->cust_main_exemption; #just to be safe
1101
1102       if ( $conf->exists('tax-pkg_address') && $cust_pkg->locationnum ) {
1103         foreach (@taxes) {
1104           $_->set('pkgnum',      $cust_pkg->pkgnum );
1105           $_->set('locationnum', $cust_pkg->locationnum );
1106         }
1107       }
1108
1109       $taxes{''} = [ @taxes ];
1110       $taxes{'setup'} = [ @taxes ];
1111       $taxes{'recur'} = [ @taxes ];
1112       $taxes{$_} = [ @taxes ] foreach (@classes);
1113
1114       # # maybe eliminate this entirely, along with all the 0% records
1115       # unless ( @taxes ) {
1116       #   return
1117       #     "fatal: can't find tax rate for state/county/country/taxclass ".
1118       #     join('/', map $taxhash{$_}, qw(state county country taxclass) );
1119       # }
1120
1121     } #if $conf->exists('enable_taxproducts') ...
1122
1123   }
1124
1125   my @display = ();
1126   my $separate = $conf->exists('separate_usage');
1127   my $temp_pkg = new FS::cust_pkg { pkgpart => $real_pkgpart };
1128   my $usage_mandate = $temp_pkg->part_pkg->option('usage_mandate', 'Hush!');
1129   my $section = $temp_pkg->part_pkg->categoryname;
1130   if ( $separate || $section || $usage_mandate ) {
1131
1132     my %hash = ( 'section' => $section );
1133
1134     $section = $temp_pkg->part_pkg->option('usage_section', 'Hush!');
1135     my $summary = $temp_pkg->part_pkg->option('summarize_usage', 'Hush!');
1136     if ( $separate ) {
1137       push @display, new FS::cust_bill_pkg_display { type => 'S', %hash };
1138       push @display, new FS::cust_bill_pkg_display { type => 'R', %hash };
1139     } else {
1140       push @display, new FS::cust_bill_pkg_display
1141                        { type => '',
1142                          %hash,
1143                          ( ( $usage_mandate ) ? ( 'summary' => 'Y' ) : () ),
1144                        };
1145     }
1146
1147     if ($separate && $section && $summary) {
1148       push @display, new FS::cust_bill_pkg_display { type    => 'U',
1149                                                      summary => 'Y',
1150                                                      %hash,
1151                                                    };
1152     }
1153     if ($usage_mandate || $section && $summary) {
1154       $hash{post_total} = 'Y';
1155     }
1156
1157     if ($separate || $usage_mandate) {
1158       $hash{section} = $section if ($separate || $usage_mandate);
1159       push @display, new FS::cust_bill_pkg_display { type => 'U', %hash };
1160     }
1161
1162   }
1163   $cust_bill_pkg->set('display', \@display);
1164
1165   my %tax_cust_bill_pkg = $cust_bill_pkg->disintegrate;
1166   foreach my $key (keys %tax_cust_bill_pkg) {
1167     my @taxes = @{ $taxes{$key} || [] };
1168     my $tax_cust_bill_pkg = $tax_cust_bill_pkg{$key};
1169
1170     my %localtaxlisthash = ();
1171     foreach my $tax ( @taxes ) {
1172
1173       my $taxname = ref( $tax ). ' '. $tax->taxnum;
1174 #      $taxname .= ' pkgnum'. $cust_pkg->pkgnum.
1175 #                  ' locationnum'. $cust_pkg->locationnum
1176 #        if $conf->exists('tax-pkg_address') && $cust_pkg->locationnum;
1177
1178       $taxlisthash->{ $taxname } ||= [ $tax ];
1179       push @{ $taxlisthash->{ $taxname  } }, $tax_cust_bill_pkg;
1180
1181       $localtaxlisthash{ $taxname } ||= [ $tax ];
1182       push @{ $localtaxlisthash{ $taxname  } }, $tax_cust_bill_pkg;
1183
1184     }
1185
1186     warn "finding taxed taxes...\n" if $DEBUG > 2;
1187     foreach my $tax ( keys %localtaxlisthash ) {
1188       my $tax_object = shift @{ $localtaxlisthash{$tax} };
1189       warn "found possible taxed tax ". $tax_object->taxname. " we call $tax\n"
1190         if $DEBUG > 2;
1191       next unless $tax_object->can('tax_on_tax');
1192
1193       foreach my $tot ( $tax_object->tax_on_tax( $self ) ) {
1194         my $totname = ref( $tot ). ' '. $tot->taxnum;
1195
1196         warn "checking $totname which we call ". $tot->taxname. " as applicable\n"
1197           if $DEBUG > 2;
1198         next unless exists( $localtaxlisthash{ $totname } ); # only increase
1199                                                              # existing taxes
1200         warn "adding $totname to taxed taxes\n" if $DEBUG > 2;
1201         my $hashref_or_error =
1202           $tax_object->taxline( $localtaxlisthash{$tax},
1203                                 'custnum'      => $self->custnum,
1204                                 'invoice_time' => $invoice_time,
1205                               );
1206         return $hashref_or_error
1207           unless ref($hashref_or_error);
1208
1209         $taxlisthash->{ $totname } ||= [ $tot ];
1210         push @{ $taxlisthash->{ $totname  } }, $hashref_or_error->{amount};
1211
1212       }
1213     }
1214
1215   }
1216
1217   '';
1218 }
1219
1220 sub _gather_taxes {
1221   my $self = shift;
1222   my $part_pkg = shift;
1223   my $class = shift;
1224   my $cust_pkg = shift;
1225
1226   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
1227
1228   my $geocode;
1229   if (  $cust_pkg->locationnum && $conf->exists('tax-pkg_address') ) {
1230     $geocode = $cust_pkg->cust_location->geocode('cch');
1231   } else {
1232     $geocode = $self->geocode('cch');
1233   }
1234
1235   my @taxes = ();
1236
1237   my @taxclassnums = map { $_->taxclassnum }
1238                      $part_pkg->part_pkg_taxoverride($class);
1239
1240   unless (@taxclassnums) {
1241     @taxclassnums = map { $_->taxclassnum }
1242                     grep { $_->taxable eq 'Y' }
1243                     $part_pkg->part_pkg_taxrate('cch', $geocode, $class);
1244   }
1245   warn "Found taxclassnum values of ". join(',', @taxclassnums)
1246     if $DEBUG;
1247
1248   my $extra_sql =
1249     "AND (".
1250     join(' OR ', map { "taxclassnum = $_" } @taxclassnums ). ")";
1251
1252   @taxes = qsearch({ 'table' => 'tax_rate',
1253                      'hashref' => { 'geocode' => $geocode, },
1254                      'extra_sql' => $extra_sql,
1255                   })
1256     if scalar(@taxclassnums);
1257
1258   warn "Found taxes ".
1259        join(',', map{ ref($_). " ". $_->get($_->primary_key) } @taxes). "\n"
1260    if $DEBUG;
1261
1262   [ @taxes ];
1263
1264 }
1265
1266 =item collect [ HASHREF | OPTION => VALUE ... ]
1267
1268 (Attempt to) collect money for this customer's outstanding invoices (see
1269 L<FS::cust_bill>).  Usually used after the bill method.
1270
1271 Actions are now triggered by billing events; see L<FS::part_event> and the
1272 billing events web interface.  Old-style invoice events (see
1273 L<FS::part_bill_event>) have been deprecated.
1274
1275 If there is an error, returns the error, otherwise returns false.
1276
1277 Options are passed as name-value pairs.
1278
1279 Currently available options are:
1280
1281 =over 4
1282
1283 =item invoice_time
1284
1285 Use this time when deciding when to print invoices and late notices on those invoices.  The default is now.  It is specified as a UNIX timestamp; see L<perlfunc/"time">).  Also see L<Time::Local> and L<Date::Parse> for conversion functions.
1286
1287 =item retry
1288
1289 Retry card/echeck/LEC transactions even when not scheduled by invoice events.
1290
1291 =item check_freq
1292
1293 "1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq)
1294
1295 =item quiet
1296
1297 set true to surpress email card/ACH decline notices.
1298
1299 =item debug
1300
1301 Debugging level.  Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)
1302
1303 =back
1304
1305 # =item payby
1306 #
1307 # allows for one time override of normal customer billing method
1308
1309 =cut
1310
1311 sub collect {
1312   my( $self, %options ) = @_;
1313
1314   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
1315
1316   my $invoice_time = $options{'invoice_time'} || time;
1317
1318   #put below somehow?
1319   local $SIG{HUP} = 'IGNORE';
1320   local $SIG{INT} = 'IGNORE';
1321   local $SIG{QUIT} = 'IGNORE';
1322   local $SIG{TERM} = 'IGNORE';
1323   local $SIG{TSTP} = 'IGNORE';
1324   local $SIG{PIPE} = 'IGNORE';
1325
1326   my $oldAutoCommit = $FS::UID::AutoCommit;
1327   local $FS::UID::AutoCommit = 0;
1328   my $dbh = dbh;
1329
1330   $self->select_for_update; #mutex
1331
1332   if ( $DEBUG ) {
1333     my $balance = $self->balance;
1334     warn "$me collect customer ". $self->custnum. ": balance $balance\n"
1335   }
1336
1337   if ( exists($options{'retry_card'}) ) {
1338     carp 'retry_card option passed to collect is deprecated; use retry';
1339     $options{'retry'} ||= $options{'retry_card'};
1340   }
1341   if ( exists($options{'retry'}) && $options{'retry'} ) {
1342     my $error = $self->retry_realtime;
1343     if ( $error ) {
1344       $dbh->rollback if $oldAutoCommit;
1345       return $error;
1346     }
1347   }
1348
1349   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
1350
1351   #never want to roll back an event just because it returned an error
1352   local $FS::UID::AutoCommit = 1; #$oldAutoCommit;
1353
1354   $self->do_cust_event(
1355     'debug'      => ( $options{'debug'} || 0 ),
1356     'time'       => $invoice_time,
1357     'check_freq' => $options{'check_freq'},
1358     'stage'      => 'collect',
1359   );
1360
1361 }
1362
1363 =item retry_realtime
1364
1365 Schedules realtime / batch  credit card / electronic check / LEC billing
1366 events for for retry.  Useful if card information has changed or manual
1367 retry is desired.  The 'collect' method must be called to actually retry
1368 the transaction.
1369
1370 Implementation details: For either this customer, or for each of this
1371 customer's open invoices, changes the status of the first "done" (with
1372 statustext error) realtime processing event to "failed".
1373
1374 =cut
1375
1376 sub retry_realtime {
1377   my $self = shift;
1378
1379   local $SIG{HUP} = 'IGNORE';
1380   local $SIG{INT} = 'IGNORE';
1381   local $SIG{QUIT} = 'IGNORE';
1382   local $SIG{TERM} = 'IGNORE';
1383   local $SIG{TSTP} = 'IGNORE';
1384   local $SIG{PIPE} = 'IGNORE';
1385
1386   my $oldAutoCommit = $FS::UID::AutoCommit;
1387   local $FS::UID::AutoCommit = 0;
1388   my $dbh = dbh;
1389
1390   #a little false laziness w/due_cust_event (not too bad, really)
1391
1392   my $join = FS::part_event_condition->join_conditions_sql;
1393   my $order = FS::part_event_condition->order_conditions_sql;
1394   my $mine =
1395   '( '
1396    . join ( ' OR ' , map {
1397     "( part_event.eventtable = " . dbh->quote($_)
1398     . " AND tablenum IN( SELECT " . dbdef->table($_)->primary_key . " from $_ where custnum = " . dbh->quote( $self->custnum ) . "))" ;
1399    } FS::part_event->eventtables)
1400    . ') ';
1401
1402   #here is the agent virtualization
1403   my $agent_virt = " (    part_event.agentnum IS NULL
1404                        OR part_event.agentnum = ". $self->agentnum. ' )';
1405
1406   #XXX this shouldn't be hardcoded, actions should declare it...
1407   my @realtime_events = qw(
1408     cust_bill_realtime_card
1409     cust_bill_realtime_check
1410     cust_bill_realtime_lec
1411     cust_bill_batch
1412   );
1413
1414   my $is_realtime_event = ' ( '. join(' OR ', map "part_event.action = '$_'",
1415                                                   @realtime_events
1416                                      ).
1417                           ' ) ';
1418
1419   my @cust_event = qsearchs({
1420     'table'     => 'cust_event',
1421     'select'    => 'cust_event.*',
1422     'addl_from' => "LEFT JOIN part_event USING ( eventpart ) $join",
1423     'hashref'   => { 'status' => 'done' },
1424     'extra_sql' => " AND statustext IS NOT NULL AND statustext != '' ".
1425                    " AND $mine AND $is_realtime_event AND $agent_virt $order" # LIMIT 1"
1426   });
1427
1428   my %seen_invnum = ();
1429   foreach my $cust_event (@cust_event) {
1430
1431     #max one for the customer, one for each open invoice
1432     my $cust_X = $cust_event->cust_X;
1433     next if $seen_invnum{ $cust_event->part_event->eventtable eq 'cust_bill'
1434                           ? $cust_X->invnum
1435                           : 0
1436                         }++
1437          or $cust_event->part_event->eventtable eq 'cust_bill'
1438             && ! $cust_X->owed;
1439
1440     my $error = $cust_event->retry;
1441     if ( $error ) {
1442       $dbh->rollback if $oldAutoCommit;
1443       return "error scheduling event for retry: $error";
1444     }
1445
1446   }
1447
1448   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
1449   '';
1450
1451 }
1452
1453 =item do_cust_event [ HASHREF | OPTION => VALUE ... ]
1454
1455 Runs billing events; see L<FS::part_event> and the billing events web
1456 interface.
1457
1458 If there is an error, returns the error, otherwise returns false.
1459
1460 Options are passed as name-value pairs.
1461
1462 Currently available options are:
1463
1464 =over 4
1465
1466 =item time
1467
1468 Use this time when deciding when to print invoices and late notices on those invoices.  The default is now.  It is specified as a UNIX timestamp; see L<perlfunc/"time">).  Also see L<Time::Local> and L<Date::Parse> for conversion functions.
1469
1470 =item check_freq
1471
1472 "1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq)
1473
1474 =item stage
1475
1476 "collect" (the default) or "pre-bill"
1477
1478 =item quiet
1479
1480 set true to surpress email card/ACH decline notices.
1481
1482 =item debug
1483
1484 Debugging level.  Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)
1485
1486 =back
1487 =cut
1488
1489 # =item payby
1490 #
1491 # allows for one time override of normal customer billing method
1492
1493 # =item retry
1494 #
1495 # Retry card/echeck/LEC transactions even when not scheduled by invoice events.
1496
1497 sub do_cust_event {
1498   my( $self, %options ) = @_;
1499
1500   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
1501
1502   my $time = $options{'time'} || time;
1503
1504   #put below somehow?
1505   local $SIG{HUP} = 'IGNORE';
1506   local $SIG{INT} = 'IGNORE';
1507   local $SIG{QUIT} = 'IGNORE';
1508   local $SIG{TERM} = 'IGNORE';
1509   local $SIG{TSTP} = 'IGNORE';
1510   local $SIG{PIPE} = 'IGNORE';
1511
1512   my $oldAutoCommit = $FS::UID::AutoCommit;
1513   local $FS::UID::AutoCommit = 0;
1514   my $dbh = dbh;
1515
1516   $self->select_for_update; #mutex
1517
1518   if ( $DEBUG ) {
1519     my $balance = $self->balance;
1520     warn "$me do_cust_event customer ". $self->custnum. ": balance $balance\n"
1521   }
1522
1523 #  if ( exists($options{'retry_card'}) ) {
1524 #    carp 'retry_card option passed to collect is deprecated; use retry';
1525 #    $options{'retry'} ||= $options{'retry_card'};
1526 #  }
1527 #  if ( exists($options{'retry'}) && $options{'retry'} ) {
1528 #    my $error = $self->retry_realtime;
1529 #    if ( $error ) {
1530 #      $dbh->rollback if $oldAutoCommit;
1531 #      return $error;
1532 #    }
1533 #  }
1534
1535   # false laziness w/pay_batch::import_results
1536
1537   my $due_cust_event = $self->due_cust_event(
1538     'debug'      => ( $options{'debug'} || 0 ),
1539     'time'       => $time,
1540     'check_freq' => $options{'check_freq'},
1541     'stage'      => ( $options{'stage'} || 'collect' ),
1542   );
1543   unless( ref($due_cust_event) ) {
1544     $dbh->rollback if $oldAutoCommit;
1545     return $due_cust_event;
1546   }
1547
1548   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
1549   #never want to roll back an event just because it or a different one
1550   # returned an error
1551   local $FS::UID::AutoCommit = 1; #$oldAutoCommit;
1552
1553   foreach my $cust_event ( @$due_cust_event ) {
1554
1555     #XXX lock event
1556
1557     #re-eval event conditions (a previous event could have changed things)
1558     unless ( $cust_event->test_conditions( 'time' => $time ) ) {
1559       #don't leave stray "new/locked" records around
1560       my $error = $cust_event->delete;
1561       return $error if $error;
1562       next;
1563     }
1564
1565     {
1566       local $FS::cust_main::Billing_Realtime::realtime_bop_decline_quiet = 1
1567         if $options{'quiet'};
1568       warn "  running cust_event ". $cust_event->eventnum. "\n"
1569         if $DEBUG > 1;
1570
1571       #if ( my $error = $cust_event->do_event(%options) ) { #XXX %options?
1572       if ( my $error = $cust_event->do_event() ) {
1573         #XXX wtf is this?  figure out a proper dealio with return value
1574         #from do_event
1575         return $error;
1576       }
1577     }
1578
1579   }
1580
1581   '';
1582
1583 }
1584
1585 =item due_cust_event [ HASHREF | OPTION => VALUE ... ]
1586
1587 Inserts database records for and returns an ordered listref of new events due
1588 for this customer, as FS::cust_event objects (see L<FS::cust_event>).  If no
1589 events are due, an empty listref is returned.  If there is an error, returns a
1590 scalar error message.
1591
1592 To actually run the events, call each event's test_condition method, and if
1593 still true, call the event's do_event method.
1594
1595 Options are passed as a hashref or as a list of name-value pairs.  Available
1596 options are:
1597
1598 =over 4
1599
1600 =item check_freq
1601
1602 Search only for events of this check frequency (how often events of this type are checked); currently "1d" (daily, the default) and "1m" (monthly) are recognized.
1603
1604 =item stage
1605
1606 "collect" (the default) or "pre-bill"
1607
1608 =item time
1609
1610 "Current time" for the events.
1611
1612 =item debug
1613
1614 Debugging level.  Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)
1615
1616 =item eventtable
1617
1618 Only return events for the specified eventtable (by default, events of all eventtables are returned)
1619
1620 =item objects
1621
1622 Explicitly pass the objects to be tested (typically used with eventtable).
1623
1624 =item testonly
1625
1626 Set to true to return the objects, but not actually insert them into the
1627 database.
1628
1629 =item discount_terms
1630
1631 Returns a list of lengths for term discounts
1632
1633 =cut
1634
1635 sub _discount_pkgs_and_bill {
1636 my $self = shift;
1637
1638   my @cust_bill = $self->cust_bill;
1639   my $cust_bill = pop @cust_bill;
1640   return () unless $cust_bill && $cust_bill->owed;
1641
1642   my @where = ();
1643   push @where, "cust_bill_pkg.invnum = ". $cust_bill->invnum;
1644   push @where, "cust_bill_pkg.pkgpart_override IS NULL";
1645   push @where, "part_pkg.freq = '1'";
1646   push @where, "(cust_pkg.cancel IS NULL OR cust_pkg.cancel = 0)";
1647   push @where, "(cust_pkg.susp   IS NULL OR cust_pkg.susp   = 0)";
1648   push @where, "0<(SELECT count(*) FROM part_pkg_discount
1649                   WHERE part_pkg.pkgpart = part_pkg_discount.pkgpart)";
1650   push @where,
1651     "0=(SELECT count(*) FROM cust_bill_pkg_discount
1652          WHERE cust_bill_pkg.billpkgnum = cust_bill_pkg_discount.billpkgnum)";
1653
1654   my $extra_sql = 'WHERE '. join(' AND ', @where);
1655
1656   my @cust_pkg =
1657     qsearch({
1658       'table' => 'cust_pkg',
1659       'select' => "DISTINCT cust_pkg.*",
1660       'addl_from' => 'JOIN cust_bill_pkg USING(pkgnum) '.
1661                      'JOIN part_pkg USING(pkgpart)',
1662       'hashref' => {},
1663       'extra_sql' => $extra_sql,
1664     });
1665
1666   ($cust_bill, @cust_pkg);
1667 }
1668
1669 sub _discountable_pkgs_at_term {
1670   my ($term, @pkgs) = @_;
1671   my $part_pkg = new FS::part_pkg { freq => $term - 1 };
1672   grep { ( !$_->adjourn || $_->adjourn > $part_pkg->add_freq($_->bill) ) &&
1673          ( !$_->expire  || $_->expire  > $part_pkg->add_freq($_->bill) )
1674        }
1675     @pkgs;
1676 }
1677
1678 =item discount_terms
1679
1680 Returns a list of lengths for term discounts
1681
1682 =cut
1683
1684 sub discount_terms {
1685 my $self = shift;
1686
1687   my %terms = ();
1688
1689   my @discount_pkgs = $self->_discount_pkgs_and_bill;
1690   shift @discount_pkgs; #discard bill;
1691
1692   map { $terms{$_->months} = 1 }
1693     grep { $_->months && $_->months > 1 }
1694     map { $_->discount }
1695     map { $_->part_pkg->part_pkg_discount }
1696     @discount_pkgs;
1697
1698   return sort { $a <=> $b } keys %terms;
1699
1700 }
1701
1702 =back
1703
1704 =item discount_term_values MONTHS
1705
1706 Returns a list with credit, dollar amount saved, and total bill acheived
1707 by prepaying the most recent invoice for MONTHS.
1708
1709 =cut
1710
1711 sub discount_term_values {
1712   my $self = shift;
1713   my $term = shift;
1714
1715   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
1716
1717   warn "$me discount_term_values called with $term\n" if $DEBUG;
1718
1719   my %result = ();
1720
1721   my @packages = $self->_discount_pkgs_and_bill;
1722   my $cust_bill = shift(@packages);
1723   @packages = _discountable_pkgs_at_term( $term, @packages );
1724   return () unless scalar(@packages);
1725
1726   $_->bill($_->last_bill) foreach @packages;
1727   my @final = map { new FS::cust_pkg { $_->hash } } @packages;
1728
1729   my %options = (
1730                   'recurring_only' => 1,
1731                   'no_usage_reset' => 1,
1732                   'no_commit'      => 1,
1733                 );
1734
1735   my %params =  (
1736                   'return_bill'    => [],
1737                   'pkg_list'       => \@packages,
1738                   'time'           => $cust_bill->_date,
1739                 );
1740
1741   my $error = $self->bill(%options, %params);
1742   die $error if $error; # XXX think about this a bit more
1743
1744   my $credit = 0;
1745   $credit += $_->charged foreach @{$params{return_bill}};
1746   $credit = sprintf('%.2f', $credit);
1747   warn "$me discount_term_values $term credit: $credit\n" if $DEBUG;
1748
1749   %params =  (
1750                'return_bill'    => [],
1751                'pkg_list'       => \@packages,
1752                'time'           => $packages[0]->part_pkg->add_freq($cust_bill->_date)
1753              );
1754
1755   $error = $self->bill(%options, %params);
1756   die $error if $error; # XXX think about this a bit more
1757
1758   my $next = 0;
1759   $next += $_->charged foreach @{$params{return_bill}};
1760   warn "$me discount_term_values $term next: $next\n" if $DEBUG;
1761
1762   %params =  (
1763                'return_bill'    => [],
1764                'pkg_list'       => \@final,
1765                'time'           => $cust_bill->_date,
1766                'freq_override'  => $term,
1767              );
1768
1769   $error = $self->bill(%options, %params);
1770   die $error if $error; # XXX think about this a bit more
1771
1772   my $final = $self->balance - $credit;
1773   $final += $_->charged foreach @{$params{return_bill}};
1774   $final = sprintf('%.2f', $final);
1775   warn "$me discount_term_values $term final: $final\n" if $DEBUG;
1776
1777   my $savings = sprintf('%.2f', $self->balance + ($term - 1) * $next - $final);
1778
1779   ( $credit, $savings, $final );
1780
1781 }
1782
1783 sub discount_terms_hash {
1784   my $self = shift;
1785
1786   my %result = ();
1787   my @terms = $self->discount_terms;
1788   foreach my $term (@terms) {
1789     my @result = $self->discount_term_values($term);
1790     $result{$term} = [ @result ] if scalar(@result);
1791   }
1792
1793   return %result;
1794
1795 }
1796
1797 =back
1798
1799 =cut
1800
1801 sub due_cust_event {
1802   my $self = shift;
1803   my %opt = ref($_[0]) ? %{ $_[0] } : @_;
1804
1805   #???
1806   #my $DEBUG = $opt{'debug'}
1807   local($DEBUG) = $opt{'debug'}
1808     if defined($opt{'debug'}) && $opt{'debug'} > $DEBUG;
1809   $DEBUG = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
1810
1811   warn "$me due_cust_event called with options ".
1812        join(', ', map { "$_: $opt{$_}" } keys %opt). "\n"
1813     if $DEBUG;
1814
1815   $opt{'time'} ||= time;
1816
1817   local $SIG{HUP} = 'IGNORE';
1818   local $SIG{INT} = 'IGNORE';
1819   local $SIG{QUIT} = 'IGNORE';
1820   local $SIG{TERM} = 'IGNORE';
1821   local $SIG{TSTP} = 'IGNORE';
1822   local $SIG{PIPE} = 'IGNORE';
1823
1824   my $oldAutoCommit = $FS::UID::AutoCommit;
1825   local $FS::UID::AutoCommit = 0;
1826   my $dbh = dbh;
1827
1828   $self->select_for_update #mutex
1829     unless $opt{testonly};
1830
1831   ###
1832   # find possible events (initial search)
1833   ###
1834
1835   my @cust_event = ();
1836
1837   my @eventtable = $opt{'eventtable'}
1838                      ? ( $opt{'eventtable'} )
1839                      : FS::part_event->eventtables_runorder;
1840
1841   my $check_freq = $opt{'check_freq'} || '1d';
1842
1843   foreach my $eventtable ( @eventtable ) {
1844
1845     my @objects;
1846     if ( $opt{'objects'} ) {
1847
1848       @objects = @{ $opt{'objects'} };
1849
1850     } else {
1851
1852       #my @objects = $self->$eventtable(); # sub cust_main { @{ [ $self ] }; }
1853       if ( $eventtable eq 'cust_main' ) {
1854         @objects = ( $self );
1855       } else {
1856
1857         my $cm_join =
1858           "LEFT JOIN cust_main USING ( custnum )";
1859
1860         #some false laziness w/Cron::bill bill_where
1861
1862         my $join  = FS::part_event_condition->join_conditions_sql( $eventtable);
1863         my $where = FS::part_event_condition->where_conditions_sql($eventtable,
1864                                                            'time'=>$opt{'time'},
1865                                                                   );
1866         $where = $where ? "AND $where" : '';
1867
1868         my $are_part_event =
1869           "EXISTS ( SELECT 1 FROM part_event $join
1870                       WHERE check_freq = '$check_freq'
1871                         AND eventtable = '$eventtable'
1872                         AND ( disabled = '' OR disabled IS NULL )
1873                         $where
1874                   )
1875           ";
1876         #eofalse
1877
1878         @objects = $self->$eventtable(
1879                      'addl_from' => $cm_join,
1880                      'extra_sql' => " AND $are_part_event",
1881                    );
1882       }
1883
1884     }
1885
1886     my @e_cust_event = ();
1887
1888     my $cross = "CROSS JOIN $eventtable";
1889     $cross .= ' LEFT JOIN cust_main USING ( custnum )'
1890       unless $eventtable eq 'cust_main';
1891
1892     foreach my $object ( @objects ) {
1893
1894       #this first search uses the condition_sql magic for optimization.
1895       #the more possible events we can eliminate in this step the better
1896
1897       my $cross_where = '';
1898       my $pkey = $object->primary_key;
1899       $cross_where = "$eventtable.$pkey = ". $object->$pkey();
1900
1901       my $join = FS::part_event_condition->join_conditions_sql( $eventtable );
1902       my $extra_sql =
1903         FS::part_event_condition->where_conditions_sql( $eventtable,
1904                                                         'time'=>$opt{'time'}
1905                                                       );
1906       my $order = FS::part_event_condition->order_conditions_sql( $eventtable );
1907
1908       $extra_sql = "AND $extra_sql" if $extra_sql;
1909
1910       #here is the agent virtualization
1911       $extra_sql .= " AND (    part_event.agentnum IS NULL
1912                             OR part_event.agentnum = ". $self->agentnum. ' )';
1913
1914       $extra_sql .= " $order";
1915
1916       warn "searching for events for $eventtable ". $object->$pkey. "\n"
1917         if $opt{'debug'} > 2;
1918       my @part_event = qsearch( {
1919         'debug'     => ( $opt{'debug'} > 3 ? 1 : 0 ),
1920         'select'    => 'part_event.*',
1921         'table'     => 'part_event',
1922         'addl_from' => "$cross $join",
1923         'hashref'   => { 'check_freq' => $check_freq,
1924                          'eventtable' => $eventtable,
1925                          'disabled'   => '',
1926                        },
1927         'extra_sql' => "AND $cross_where $extra_sql",
1928       } );
1929
1930       if ( $DEBUG > 2 ) {
1931         my $pkey = $object->primary_key;
1932         warn "      ". scalar(@part_event).
1933              " possible events found for $eventtable ". $object->$pkey(). "\n";
1934       }
1935
1936       push @e_cust_event, map { $_->new_cust_event($object) } @part_event;
1937
1938     }
1939
1940     warn "    ". scalar(@e_cust_event).
1941          " subtotal possible cust events found for $eventtable\n"
1942       if $DEBUG > 1;
1943
1944     push @cust_event, @e_cust_event;
1945
1946   }
1947
1948   warn "  ". scalar(@cust_event).
1949        " total possible cust events found in initial search\n"
1950     if $DEBUG; # > 1;
1951
1952
1953   ##
1954   # test stage
1955   ##
1956
1957   $opt{stage} ||= 'collect';
1958   @cust_event =
1959     grep { my $stage = $_->part_event->event_stage;
1960            $opt{stage} eq $stage or ( ! $stage && $opt{stage} eq 'collect' )
1961          }
1962          @cust_event;
1963
1964   ##
1965   # test conditions
1966   ##
1967
1968   my %unsat = ();
1969
1970   @cust_event = grep $_->test_conditions( 'time'          => $opt{'time'},
1971                                           'stats_hashref' => \%unsat ),
1972                      @cust_event;
1973
1974   warn "  ". scalar(@cust_event). " cust events left satisfying conditions\n"
1975     if $DEBUG; # > 1;
1976
1977   warn "    invalid conditions not eliminated with condition_sql:\n".
1978        join('', map "      $_: ".$unsat{$_}."\n", keys %unsat )
1979     if keys %unsat && $DEBUG; # > 1;
1980
1981   ##
1982   # insert
1983   ##
1984
1985   unless( $opt{testonly} ) {
1986     foreach my $cust_event ( @cust_event ) {
1987
1988       my $error = $cust_event->insert();
1989       if ( $error ) {
1990         $dbh->rollback if $oldAutoCommit;
1991         return $error;
1992       }
1993
1994     }
1995   }
1996
1997   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
1998
1999   ##
2000   # return
2001   ##
2002
2003   warn "  returning events: ". Dumper(@cust_event). "\n"
2004     if $DEBUG > 2;
2005
2006   \@cust_event;
2007
2008 }
2009
2010 =item apply_payments_and_credits [ OPTION => VALUE ... ]
2011
2012 Applies unapplied payments and credits.
2013
2014 In most cases, this new method should be used in place of sequential
2015 apply_payments and apply_credits methods.
2016
2017 A hash of optional arguments may be passed.  Currently "manual" is supported.
2018 If true, a payment receipt is sent instead of a statement when
2019 'payment_receipt_email' configuration option is set.
2020
2021 If there is an error, returns the error, otherwise returns false.
2022
2023 =cut
2024
2025 sub apply_payments_and_credits {
2026   my( $self, %options ) = @_;
2027
2028   local $SIG{HUP} = 'IGNORE';
2029   local $SIG{INT} = 'IGNORE';
2030   local $SIG{QUIT} = 'IGNORE';
2031   local $SIG{TERM} = 'IGNORE';
2032   local $SIG{TSTP} = 'IGNORE';
2033   local $SIG{PIPE} = 'IGNORE';
2034
2035   my $oldAutoCommit = $FS::UID::AutoCommit;
2036   local $FS::UID::AutoCommit = 0;
2037   my $dbh = dbh;
2038
2039   $self->select_for_update; #mutex
2040
2041   foreach my $cust_bill ( $self->open_cust_bill ) {
2042     my $error = $cust_bill->apply_payments_and_credits(%options);
2043     if ( $error ) {
2044       $dbh->rollback if $oldAutoCommit;
2045       return "Error applying: $error";
2046     }
2047   }
2048
2049   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
2050   ''; #no error
2051
2052 }
2053
2054 =item apply_credits OPTION => VALUE ...
2055
2056 Applies (see L<FS::cust_credit_bill>) unapplied credits (see L<FS::cust_credit>)
2057 to outstanding invoice balances in chronological order (or reverse
2058 chronological order if the I<order> option is set to B<newest>) and returns the
2059 value of any remaining unapplied credits available for refund (see
2060 L<FS::cust_refund>).
2061
2062 Dies if there is an error.
2063
2064 =cut
2065
2066 sub apply_credits {
2067   my $self = shift;
2068   my %opt = @_;
2069
2070   local $SIG{HUP} = 'IGNORE';
2071   local $SIG{INT} = 'IGNORE';
2072   local $SIG{QUIT} = 'IGNORE';
2073   local $SIG{TERM} = 'IGNORE';
2074   local $SIG{TSTP} = 'IGNORE';
2075   local $SIG{PIPE} = 'IGNORE';
2076
2077   my $oldAutoCommit = $FS::UID::AutoCommit;
2078   local $FS::UID::AutoCommit = 0;
2079   my $dbh = dbh;
2080
2081   $self->select_for_update; #mutex
2082
2083   unless ( $self->total_unapplied_credits ) {
2084     $dbh->commit or die $dbh->errstr if $oldAutoCommit;
2085     return 0;
2086   }
2087
2088   my @credits = sort { $b->_date <=> $a->_date} (grep { $_->credited > 0 }
2089       qsearch('cust_credit', { 'custnum' => $self->custnum } ) );
2090
2091   my @invoices = $self->open_cust_bill;
2092   @invoices = sort { $b->_date <=> $a->_date } @invoices
2093     if defined($opt{'order'}) && $opt{'order'} eq 'newest';
2094
2095   if ( $conf->exists('pkg-balances') ) {
2096     # limit @credits to those w/ a pkgnum grepped from $self
2097     my %pkgnums = ();
2098     foreach my $i (@invoices) {
2099       foreach my $li ( $i->cust_bill_pkg ) {
2100         $pkgnums{$li->pkgnum} = 1;
2101       }
2102     }
2103     @credits = grep { ! $_->pkgnum || $pkgnums{$_->pkgnum} } @credits;
2104   }
2105
2106   my $credit;
2107
2108   foreach my $cust_bill ( @invoices ) {
2109
2110     if ( !defined($credit) || $credit->credited == 0) {
2111       $credit = pop @credits or last;
2112     }
2113
2114     my $owed;
2115     if ( $conf->exists('pkg-balances') && $credit->pkgnum ) {
2116       $owed = $cust_bill->owed_pkgnum($credit->pkgnum);
2117     } else {
2118       $owed = $cust_bill->owed;
2119     }
2120     unless ( $owed > 0 ) {
2121       push @credits, $credit;
2122       next;
2123     }
2124
2125     my $amount = min( $credit->credited, $owed );
2126
2127     my $cust_credit_bill = new FS::cust_credit_bill ( {
2128       'crednum' => $credit->crednum,
2129       'invnum'  => $cust_bill->invnum,
2130       'amount'  => $amount,
2131     } );
2132     $cust_credit_bill->pkgnum( $credit->pkgnum )
2133       if $conf->exists('pkg-balances') && $credit->pkgnum;
2134     my $error = $cust_credit_bill->insert;
2135     if ( $error ) {
2136       $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
2137       die $error;
2138     }
2139
2140     redo if ($cust_bill->owed > 0) && ! $conf->exists('pkg-balances');
2141
2142   }
2143
2144   my $total_unapplied_credits = $self->total_unapplied_credits;
2145
2146   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
2147
2148   return $total_unapplied_credits;
2149 }
2150
2151 =item apply_payments  [ OPTION => VALUE ... ]
2152
2153 Applies (see L<FS::cust_bill_pay>) unapplied payments (see L<FS::cust_pay>)
2154 to outstanding invoice balances in chronological order.
2155
2156  #and returns the value of any remaining unapplied payments.
2157
2158 A hash of optional arguments may be passed.  Currently "manual" is supported.
2159 If true, a payment receipt is sent instead of a statement when
2160 'payment_receipt_email' configuration option is set.
2161
2162 Dies if there is an error.
2163
2164 =cut
2165
2166 sub apply_payments {
2167   my( $self, %options ) = @_;
2168
2169   local $SIG{HUP} = 'IGNORE';
2170   local $SIG{INT} = 'IGNORE';
2171   local $SIG{QUIT} = 'IGNORE';
2172   local $SIG{TERM} = 'IGNORE';
2173   local $SIG{TSTP} = 'IGNORE';
2174   local $SIG{PIPE} = 'IGNORE';
2175
2176   my $oldAutoCommit = $FS::UID::AutoCommit;
2177   local $FS::UID::AutoCommit = 0;
2178   my $dbh = dbh;
2179
2180   $self->select_for_update; #mutex
2181
2182   #return 0 unless
2183
2184   my @payments = sort { $b->_date <=> $a->_date }
2185                  grep { $_->unapplied > 0 }
2186                  $self->cust_pay;
2187
2188   my @invoices = sort { $a->_date <=> $b->_date}
2189                  grep { $_->owed > 0 }
2190                  $self->cust_bill;
2191
2192   if ( $conf->exists('pkg-balances') ) {
2193     # limit @payments to those w/ a pkgnum grepped from $self
2194     my %pkgnums = ();
2195     foreach my $i (@invoices) {
2196       foreach my $li ( $i->cust_bill_pkg ) {
2197         $pkgnums{$li->pkgnum} = 1;
2198       }
2199     }
2200     @payments = grep { ! $_->pkgnum || $pkgnums{$_->pkgnum} } @payments;
2201   }
2202
2203   my $payment;
2204
2205   foreach my $cust_bill ( @invoices ) {
2206
2207     if ( !defined($payment) || $payment->unapplied == 0 ) {
2208       $payment = pop @payments or last;
2209     }
2210
2211     my $owed;
2212     if ( $conf->exists('pkg-balances') && $payment->pkgnum ) {
2213       $owed = $cust_bill->owed_pkgnum($payment->pkgnum);
2214     } else {
2215       $owed = $cust_bill->owed;
2216     }
2217     unless ( $owed > 0 ) {
2218       push @payments, $payment;
2219       next;
2220     }
2221
2222     my $amount = min( $payment->unapplied, $owed );
2223
2224     my $cust_bill_pay = new FS::cust_bill_pay ( {
2225       'paynum' => $payment->paynum,
2226       'invnum' => $cust_bill->invnum,
2227       'amount' => $amount,
2228     } );
2229     $cust_bill_pay->pkgnum( $payment->pkgnum )
2230       if $conf->exists('pkg-balances') && $payment->pkgnum;
2231     my $error = $cust_bill_pay->insert(%options);
2232     if ( $error ) {
2233       $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
2234       die $error;
2235     }
2236
2237     redo if ( $cust_bill->owed > 0) && ! $conf->exists('pkg-balances');
2238
2239   }
2240
2241   my $total_unapplied_payments = $self->total_unapplied_payments;
2242
2243   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
2244
2245   return $total_unapplied_payments;
2246 }
2247
2248 =head1 BUGS
2249
2250 =head1 SEE ALSO
2251
2252 L<FS::cust_main>, L<FS::cust_main::Billing_Realtime>
2253
2254 =cut
2255
2256 1;