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 = $self->geocode('cch');
1229   $geocode = $cust_pkg->cust_location->geocode('cch')
1230     if ( $conf->exists('tax-pkg_address') && $cust_pkg->locationnum );
1231   my @taxes = ();
1232
1233   my @taxclassnums = map { $_->taxclassnum }
1234                      $part_pkg->part_pkg_taxoverride($class);
1235
1236   unless (@taxclassnums) {
1237     @taxclassnums = map { $_->taxclassnum }
1238                     grep { $_->taxable eq 'Y' }
1239                     $part_pkg->part_pkg_taxrate('cch', $geocode, $class);
1240   }
1241   warn "Found taxclassnum values of ". join(',', @taxclassnums)
1242     if $DEBUG;
1243
1244   my $extra_sql =
1245     "AND (".
1246     join(' OR ', map { "taxclassnum = $_" } @taxclassnums ). ")";
1247
1248   @taxes = qsearch({ 'table' => 'tax_rate',
1249                      'hashref' => { 'geocode' => $geocode, },
1250                      'extra_sql' => $extra_sql,
1251                   })
1252     if scalar(@taxclassnums);
1253
1254   warn "Found taxes ".
1255        join(',', map{ ref($_). " ". $_->get($_->primary_key) } @taxes). "\n"
1256    if $DEBUG;
1257
1258   [ @taxes ];
1259
1260 }
1261
1262 =item collect [ HASHREF | OPTION => VALUE ... ]
1263
1264 (Attempt to) collect money for this customer's outstanding invoices (see
1265 L<FS::cust_bill>).  Usually used after the bill method.
1266
1267 Actions are now triggered by billing events; see L<FS::part_event> and the
1268 billing events web interface.  Old-style invoice events (see
1269 L<FS::part_bill_event>) have been deprecated.
1270
1271 If there is an error, returns the error, otherwise returns false.
1272
1273 Options are passed as name-value pairs.
1274
1275 Currently available options are:
1276
1277 =over 4
1278
1279 =item invoice_time
1280
1281 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.
1282
1283 =item retry
1284
1285 Retry card/echeck/LEC transactions even when not scheduled by invoice events.
1286
1287 =item check_freq
1288
1289 "1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq)
1290
1291 =item quiet
1292
1293 set true to surpress email card/ACH decline notices.
1294
1295 =item debug
1296
1297 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)
1298
1299 =back
1300
1301 # =item payby
1302 #
1303 # allows for one time override of normal customer billing method
1304
1305 =cut
1306
1307 sub collect {
1308   my( $self, %options ) = @_;
1309
1310   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
1311
1312   my $invoice_time = $options{'invoice_time'} || time;
1313
1314   #put below somehow?
1315   local $SIG{HUP} = 'IGNORE';
1316   local $SIG{INT} = 'IGNORE';
1317   local $SIG{QUIT} = 'IGNORE';
1318   local $SIG{TERM} = 'IGNORE';
1319   local $SIG{TSTP} = 'IGNORE';
1320   local $SIG{PIPE} = 'IGNORE';
1321
1322   my $oldAutoCommit = $FS::UID::AutoCommit;
1323   local $FS::UID::AutoCommit = 0;
1324   my $dbh = dbh;
1325
1326   $self->select_for_update; #mutex
1327
1328   if ( $DEBUG ) {
1329     my $balance = $self->balance;
1330     warn "$me collect customer ". $self->custnum. ": balance $balance\n"
1331   }
1332
1333   if ( exists($options{'retry_card'}) ) {
1334     carp 'retry_card option passed to collect is deprecated; use retry';
1335     $options{'retry'} ||= $options{'retry_card'};
1336   }
1337   if ( exists($options{'retry'}) && $options{'retry'} ) {
1338     my $error = $self->retry_realtime;
1339     if ( $error ) {
1340       $dbh->rollback if $oldAutoCommit;
1341       return $error;
1342     }
1343   }
1344
1345   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
1346
1347   #never want to roll back an event just because it returned an error
1348   local $FS::UID::AutoCommit = 1; #$oldAutoCommit;
1349
1350   $self->do_cust_event(
1351     'debug'      => ( $options{'debug'} || 0 ),
1352     'time'       => $invoice_time,
1353     'check_freq' => $options{'check_freq'},
1354     'stage'      => 'collect',
1355   );
1356
1357 }
1358
1359 =item retry_realtime
1360
1361 Schedules realtime / batch  credit card / electronic check / LEC billing
1362 events for for retry.  Useful if card information has changed or manual
1363 retry is desired.  The 'collect' method must be called to actually retry
1364 the transaction.
1365
1366 Implementation details: For either this customer, or for each of this
1367 customer's open invoices, changes the status of the first "done" (with
1368 statustext error) realtime processing event to "failed".
1369
1370 =cut
1371
1372 sub retry_realtime {
1373   my $self = shift;
1374
1375   local $SIG{HUP} = 'IGNORE';
1376   local $SIG{INT} = 'IGNORE';
1377   local $SIG{QUIT} = 'IGNORE';
1378   local $SIG{TERM} = 'IGNORE';
1379   local $SIG{TSTP} = 'IGNORE';
1380   local $SIG{PIPE} = 'IGNORE';
1381
1382   my $oldAutoCommit = $FS::UID::AutoCommit;
1383   local $FS::UID::AutoCommit = 0;
1384   my $dbh = dbh;
1385
1386   #a little false laziness w/due_cust_event (not too bad, really)
1387
1388   my $join = FS::part_event_condition->join_conditions_sql;
1389   my $order = FS::part_event_condition->order_conditions_sql;
1390   my $mine =
1391   '( '
1392    . join ( ' OR ' , map {
1393     "( part_event.eventtable = " . dbh->quote($_)
1394     . " AND tablenum IN( SELECT " . dbdef->table($_)->primary_key . " from $_ where custnum = " . dbh->quote( $self->custnum ) . "))" ;
1395    } FS::part_event->eventtables)
1396    . ') ';
1397
1398   #here is the agent virtualization
1399   my $agent_virt = " (    part_event.agentnum IS NULL
1400                        OR part_event.agentnum = ". $self->agentnum. ' )';
1401
1402   #XXX this shouldn't be hardcoded, actions should declare it...
1403   my @realtime_events = qw(
1404     cust_bill_realtime_card
1405     cust_bill_realtime_check
1406     cust_bill_realtime_lec
1407     cust_bill_batch
1408   );
1409
1410   my $is_realtime_event = ' ( '. join(' OR ', map "part_event.action = '$_'",
1411                                                   @realtime_events
1412                                      ).
1413                           ' ) ';
1414
1415   my @cust_event = qsearchs({
1416     'table'     => 'cust_event',
1417     'select'    => 'cust_event.*',
1418     'addl_from' => "LEFT JOIN part_event USING ( eventpart ) $join",
1419     'hashref'   => { 'status' => 'done' },
1420     'extra_sql' => " AND statustext IS NOT NULL AND statustext != '' ".
1421                    " AND $mine AND $is_realtime_event AND $agent_virt $order" # LIMIT 1"
1422   });
1423
1424   my %seen_invnum = ();
1425   foreach my $cust_event (@cust_event) {
1426
1427     #max one for the customer, one for each open invoice
1428     my $cust_X = $cust_event->cust_X;
1429     next if $seen_invnum{ $cust_event->part_event->eventtable eq 'cust_bill'
1430                           ? $cust_X->invnum
1431                           : 0
1432                         }++
1433          or $cust_event->part_event->eventtable eq 'cust_bill'
1434             && ! $cust_X->owed;
1435
1436     my $error = $cust_event->retry;
1437     if ( $error ) {
1438       $dbh->rollback if $oldAutoCommit;
1439       return "error scheduling event for retry: $error";
1440     }
1441
1442   }
1443
1444   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
1445   '';
1446
1447 }
1448
1449 =item do_cust_event [ HASHREF | OPTION => VALUE ... ]
1450
1451 Runs billing events; see L<FS::part_event> and the billing events web
1452 interface.
1453
1454 If there is an error, returns the error, otherwise returns false.
1455
1456 Options are passed as name-value pairs.
1457
1458 Currently available options are:
1459
1460 =over 4
1461
1462 =item time
1463
1464 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.
1465
1466 =item check_freq
1467
1468 "1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq)
1469
1470 =item stage
1471
1472 "collect" (the default) or "pre-bill"
1473
1474 =item quiet
1475
1476 set true to surpress email card/ACH decline notices.
1477
1478 =item debug
1479
1480 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)
1481
1482 =back
1483 =cut
1484
1485 # =item payby
1486 #
1487 # allows for one time override of normal customer billing method
1488
1489 # =item retry
1490 #
1491 # Retry card/echeck/LEC transactions even when not scheduled by invoice events.
1492
1493 sub do_cust_event {
1494   my( $self, %options ) = @_;
1495
1496   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
1497
1498   my $time = $options{'time'} || time;
1499
1500   #put below somehow?
1501   local $SIG{HUP} = 'IGNORE';
1502   local $SIG{INT} = 'IGNORE';
1503   local $SIG{QUIT} = 'IGNORE';
1504   local $SIG{TERM} = 'IGNORE';
1505   local $SIG{TSTP} = 'IGNORE';
1506   local $SIG{PIPE} = 'IGNORE';
1507
1508   my $oldAutoCommit = $FS::UID::AutoCommit;
1509   local $FS::UID::AutoCommit = 0;
1510   my $dbh = dbh;
1511
1512   $self->select_for_update; #mutex
1513
1514   if ( $DEBUG ) {
1515     my $balance = $self->balance;
1516     warn "$me do_cust_event customer ". $self->custnum. ": balance $balance\n"
1517   }
1518
1519 #  if ( exists($options{'retry_card'}) ) {
1520 #    carp 'retry_card option passed to collect is deprecated; use retry';
1521 #    $options{'retry'} ||= $options{'retry_card'};
1522 #  }
1523 #  if ( exists($options{'retry'}) && $options{'retry'} ) {
1524 #    my $error = $self->retry_realtime;
1525 #    if ( $error ) {
1526 #      $dbh->rollback if $oldAutoCommit;
1527 #      return $error;
1528 #    }
1529 #  }
1530
1531   # false laziness w/pay_batch::import_results
1532
1533   my $due_cust_event = $self->due_cust_event(
1534     'debug'      => ( $options{'debug'} || 0 ),
1535     'time'       => $time,
1536     'check_freq' => $options{'check_freq'},
1537     'stage'      => ( $options{'stage'} || 'collect' ),
1538   );
1539   unless( ref($due_cust_event) ) {
1540     $dbh->rollback if $oldAutoCommit;
1541     return $due_cust_event;
1542   }
1543
1544   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
1545   #never want to roll back an event just because it or a different one
1546   # returned an error
1547   local $FS::UID::AutoCommit = 1; #$oldAutoCommit;
1548
1549   foreach my $cust_event ( @$due_cust_event ) {
1550
1551     #XXX lock event
1552
1553     #re-eval event conditions (a previous event could have changed things)
1554     unless ( $cust_event->test_conditions( 'time' => $time ) ) {
1555       #don't leave stray "new/locked" records around
1556       my $error = $cust_event->delete;
1557       return $error if $error;
1558       next;
1559     }
1560
1561     {
1562       local $FS::cust_main::Billing_Realtime::realtime_bop_decline_quiet = 1
1563         if $options{'quiet'};
1564       warn "  running cust_event ". $cust_event->eventnum. "\n"
1565         if $DEBUG > 1;
1566
1567       #if ( my $error = $cust_event->do_event(%options) ) { #XXX %options?
1568       if ( my $error = $cust_event->do_event() ) {
1569         #XXX wtf is this?  figure out a proper dealio with return value
1570         #from do_event
1571         return $error;
1572       }
1573     }
1574
1575   }
1576
1577   '';
1578
1579 }
1580
1581 =item due_cust_event [ HASHREF | OPTION => VALUE ... ]
1582
1583 Inserts database records for and returns an ordered listref of new events due
1584 for this customer, as FS::cust_event objects (see L<FS::cust_event>).  If no
1585 events are due, an empty listref is returned.  If there is an error, returns a
1586 scalar error message.
1587
1588 To actually run the events, call each event's test_condition method, and if
1589 still true, call the event's do_event method.
1590
1591 Options are passed as a hashref or as a list of name-value pairs.  Available
1592 options are:
1593
1594 =over 4
1595
1596 =item check_freq
1597
1598 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.
1599
1600 =item stage
1601
1602 "collect" (the default) or "pre-bill"
1603
1604 =item time
1605
1606 "Current time" for the events.
1607
1608 =item debug
1609
1610 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)
1611
1612 =item eventtable
1613
1614 Only return events for the specified eventtable (by default, events of all eventtables are returned)
1615
1616 =item objects
1617
1618 Explicitly pass the objects to be tested (typically used with eventtable).
1619
1620 =item testonly
1621
1622 Set to true to return the objects, but not actually insert them into the
1623 database.
1624
1625 =item discount_terms
1626
1627 Returns a list of lengths for term discounts
1628
1629 =cut
1630
1631 sub _discount_pkgs_and_bill {
1632 my $self = shift;
1633
1634   my @cust_bill = $self->cust_bill;
1635   my $cust_bill = pop @cust_bill;
1636   return () unless $cust_bill && $cust_bill->owed;
1637
1638   my @where = ();
1639   push @where, "cust_bill_pkg.invnum = ". $cust_bill->invnum;
1640   push @where, "cust_bill_pkg.pkgpart_override IS NULL";
1641   push @where, "part_pkg.freq = '1'";
1642   push @where, "(cust_pkg.cancel IS NULL OR cust_pkg.cancel = 0)";
1643   push @where, "(cust_pkg.susp   IS NULL OR cust_pkg.susp   = 0)";
1644   push @where, "0<(SELECT count(*) FROM part_pkg_discount
1645                   WHERE part_pkg.pkgpart = part_pkg_discount.pkgpart)";
1646   push @where,
1647     "0=(SELECT count(*) FROM cust_bill_pkg_discount
1648          WHERE cust_bill_pkg.billpkgnum = cust_bill_pkg_discount.billpkgnum)";
1649
1650   my $extra_sql = 'WHERE '. join(' AND ', @where);
1651
1652   my @cust_pkg =
1653     qsearch({
1654       'table' => 'cust_pkg',
1655       'select' => "DISTINCT cust_pkg.*",
1656       'addl_from' => 'JOIN cust_bill_pkg USING(pkgnum) '.
1657                      'JOIN part_pkg USING(pkgpart)',
1658       'hashref' => {},
1659       'extra_sql' => $extra_sql,
1660     });
1661
1662   ($cust_bill, @cust_pkg);
1663 }
1664
1665 sub _discountable_pkgs_at_term {
1666   my ($term, @pkgs) = @_;
1667   my $part_pkg = new FS::part_pkg { freq => $term - 1 };
1668   grep { ( !$_->adjourn || $_->adjourn > $part_pkg->add_freq($_->bill) ) &&
1669          ( !$_->expire  || $_->expire  > $part_pkg->add_freq($_->bill) )
1670        }
1671     @pkgs;
1672 }
1673
1674 =item discount_terms
1675
1676 Returns a list of lengths for term discounts
1677
1678 =cut
1679
1680 sub discount_terms {
1681 my $self = shift;
1682
1683   my %terms = ();
1684
1685   my @discount_pkgs = $self->_discount_pkgs_and_bill;
1686   shift @discount_pkgs; #discard bill;
1687
1688   map { $terms{$_->months} = 1 }
1689     grep { $_->months && $_->months > 1 }
1690     map { $_->discount }
1691     map { $_->part_pkg->part_pkg_discount }
1692     @discount_pkgs;
1693
1694   return sort { $a <=> $b } keys %terms;
1695
1696 }
1697
1698 =back
1699
1700 =item discount_term_values MONTHS
1701
1702 Returns a list with credit, dollar amount saved, and total bill acheived
1703 by prepaying the most recent invoice for MONTHS.
1704
1705 =cut
1706
1707 sub discount_term_values {
1708   my $self = shift;
1709   my $term = shift;
1710
1711   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
1712
1713   warn "$me discount_term_values called with $term\n" if $DEBUG;
1714
1715   my %result = ();
1716
1717   my @packages = $self->_discount_pkgs_and_bill;
1718   my $cust_bill = shift(@packages);
1719   @packages = _discountable_pkgs_at_term( $term, @packages );
1720   return () unless scalar(@packages);
1721
1722   $_->bill($_->last_bill) foreach @packages;
1723   my @final = map { new FS::cust_pkg { $_->hash } } @packages;
1724
1725   my %options = (
1726                   'recurring_only' => 1,
1727                   'no_usage_reset' => 1,
1728                   'no_commit'      => 1,
1729                 );
1730
1731   my %params =  (
1732                   'return_bill'    => [],
1733                   'pkg_list'       => \@packages,
1734                   'time'           => $cust_bill->_date,
1735                 );
1736
1737   my $error = $self->bill(%options, %params);
1738   die $error if $error; # XXX think about this a bit more
1739
1740   my $credit = 0;
1741   $credit += $_->charged foreach @{$params{return_bill}};
1742   $credit = sprintf('%.2f', $credit);
1743   warn "$me discount_term_values $term credit: $credit\n" if $DEBUG;
1744
1745   %params =  (
1746                'return_bill'    => [],
1747                'pkg_list'       => \@packages,
1748                'time'           => $packages[0]->part_pkg->add_freq($cust_bill->_date)
1749              );
1750
1751   $error = $self->bill(%options, %params);
1752   die $error if $error; # XXX think about this a bit more
1753
1754   my $next = 0;
1755   $next += $_->charged foreach @{$params{return_bill}};
1756   warn "$me discount_term_values $term next: $next\n" if $DEBUG;
1757
1758   %params =  (
1759                'return_bill'    => [],
1760                'pkg_list'       => \@final,
1761                'time'           => $cust_bill->_date,
1762                'freq_override'  => $term,
1763              );
1764
1765   $error = $self->bill(%options, %params);
1766   die $error if $error; # XXX think about this a bit more
1767
1768   my $final = $self->balance - $credit;
1769   $final += $_->charged foreach @{$params{return_bill}};
1770   $final = sprintf('%.2f', $final);
1771   warn "$me discount_term_values $term final: $final\n" if $DEBUG;
1772
1773   my $savings = sprintf('%.2f', $self->balance + ($term - 1) * $next - $final);
1774
1775   ( $credit, $savings, $final );
1776
1777 }
1778
1779 sub discount_terms_hash {
1780   my $self = shift;
1781
1782   my %result = ();
1783   my @terms = $self->discount_terms;
1784   foreach my $term (@terms) {
1785     my @result = $self->discount_term_values($term);
1786     $result{$term} = [ @result ] if scalar(@result);
1787   }
1788
1789   return %result;
1790
1791 }
1792
1793 =back
1794
1795 =cut
1796
1797 sub due_cust_event {
1798   my $self = shift;
1799   my %opt = ref($_[0]) ? %{ $_[0] } : @_;
1800
1801   #???
1802   #my $DEBUG = $opt{'debug'}
1803   local($DEBUG) = $opt{'debug'}
1804     if defined($opt{'debug'}) && $opt{'debug'} > $DEBUG;
1805   $DEBUG = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
1806
1807   warn "$me due_cust_event called with options ".
1808        join(', ', map { "$_: $opt{$_}" } keys %opt). "\n"
1809     if $DEBUG;
1810
1811   $opt{'time'} ||= time;
1812
1813   local $SIG{HUP} = 'IGNORE';
1814   local $SIG{INT} = 'IGNORE';
1815   local $SIG{QUIT} = 'IGNORE';
1816   local $SIG{TERM} = 'IGNORE';
1817   local $SIG{TSTP} = 'IGNORE';
1818   local $SIG{PIPE} = 'IGNORE';
1819
1820   my $oldAutoCommit = $FS::UID::AutoCommit;
1821   local $FS::UID::AutoCommit = 0;
1822   my $dbh = dbh;
1823
1824   $self->select_for_update #mutex
1825     unless $opt{testonly};
1826
1827   ###
1828   # find possible events (initial search)
1829   ###
1830
1831   my @cust_event = ();
1832
1833   my @eventtable = $opt{'eventtable'}
1834                      ? ( $opt{'eventtable'} )
1835                      : FS::part_event->eventtables_runorder;
1836
1837   my $check_freq = $opt{'check_freq'} || '1d';
1838
1839   foreach my $eventtable ( @eventtable ) {
1840
1841     my @objects;
1842     if ( $opt{'objects'} ) {
1843
1844       @objects = @{ $opt{'objects'} };
1845
1846     } else {
1847
1848       #my @objects = $self->$eventtable(); # sub cust_main { @{ [ $self ] }; }
1849       if ( $eventtable eq 'cust_main' ) {
1850         @objects = ( $self );
1851       } else {
1852
1853         my $cm_join =
1854           "LEFT JOIN cust_main USING ( custnum )";
1855
1856         #some false laziness w/Cron::bill bill_where
1857
1858         my $join  = FS::part_event_condition->join_conditions_sql( $eventtable);
1859         my $where = FS::part_event_condition->where_conditions_sql($eventtable,
1860                                                            'time'=>$opt{'time'},
1861                                                                   );
1862         $where = $where ? "AND $where" : '';
1863
1864         my $are_part_event =
1865           "EXISTS ( SELECT 1 FROM part_event $join
1866                       WHERE check_freq = '$check_freq'
1867                         AND eventtable = '$eventtable'
1868                         AND ( disabled = '' OR disabled IS NULL )
1869                         $where
1870                   )
1871           ";
1872         #eofalse
1873
1874         @objects = $self->$eventtable(
1875                      'addl_from' => $cm_join,
1876                      'extra_sql' => " AND $are_part_event",
1877                    );
1878       }
1879
1880     }
1881
1882     my @e_cust_event = ();
1883
1884     my $cross = "CROSS JOIN $eventtable";
1885     $cross .= ' LEFT JOIN cust_main USING ( custnum )'
1886       unless $eventtable eq 'cust_main';
1887
1888     foreach my $object ( @objects ) {
1889
1890       #this first search uses the condition_sql magic for optimization.
1891       #the more possible events we can eliminate in this step the better
1892
1893       my $cross_where = '';
1894       my $pkey = $object->primary_key;
1895       $cross_where = "$eventtable.$pkey = ". $object->$pkey();
1896
1897       my $join = FS::part_event_condition->join_conditions_sql( $eventtable );
1898       my $extra_sql =
1899         FS::part_event_condition->where_conditions_sql( $eventtable,
1900                                                         'time'=>$opt{'time'}
1901                                                       );
1902       my $order = FS::part_event_condition->order_conditions_sql( $eventtable );
1903
1904       $extra_sql = "AND $extra_sql" if $extra_sql;
1905
1906       #here is the agent virtualization
1907       $extra_sql .= " AND (    part_event.agentnum IS NULL
1908                             OR part_event.agentnum = ". $self->agentnum. ' )';
1909
1910       $extra_sql .= " $order";
1911
1912       warn "searching for events for $eventtable ". $object->$pkey. "\n"
1913         if $opt{'debug'} > 2;
1914       my @part_event = qsearch( {
1915         'debug'     => ( $opt{'debug'} > 3 ? 1 : 0 ),
1916         'select'    => 'part_event.*',
1917         'table'     => 'part_event',
1918         'addl_from' => "$cross $join",
1919         'hashref'   => { 'check_freq' => $check_freq,
1920                          'eventtable' => $eventtable,
1921                          'disabled'   => '',
1922                        },
1923         'extra_sql' => "AND $cross_where $extra_sql",
1924       } );
1925
1926       if ( $DEBUG > 2 ) {
1927         my $pkey = $object->primary_key;
1928         warn "      ". scalar(@part_event).
1929              " possible events found for $eventtable ". $object->$pkey(). "\n";
1930       }
1931
1932       push @e_cust_event, map { $_->new_cust_event($object) } @part_event;
1933
1934     }
1935
1936     warn "    ". scalar(@e_cust_event).
1937          " subtotal possible cust events found for $eventtable\n"
1938       if $DEBUG > 1;
1939
1940     push @cust_event, @e_cust_event;
1941
1942   }
1943
1944   warn "  ". scalar(@cust_event).
1945        " total possible cust events found in initial search\n"
1946     if $DEBUG; # > 1;
1947
1948
1949   ##
1950   # test stage
1951   ##
1952
1953   $opt{stage} ||= 'collect';
1954   @cust_event =
1955     grep { my $stage = $_->part_event->event_stage;
1956            $opt{stage} eq $stage or ( ! $stage && $opt{stage} eq 'collect' )
1957          }
1958          @cust_event;
1959
1960   ##
1961   # test conditions
1962   ##
1963
1964   my %unsat = ();
1965
1966   @cust_event = grep $_->test_conditions( 'time'          => $opt{'time'},
1967                                           'stats_hashref' => \%unsat ),
1968                      @cust_event;
1969
1970   warn "  ". scalar(@cust_event). " cust events left satisfying conditions\n"
1971     if $DEBUG; # > 1;
1972
1973   warn "    invalid conditions not eliminated with condition_sql:\n".
1974        join('', map "      $_: ".$unsat{$_}."\n", keys %unsat )
1975     if keys %unsat && $DEBUG; # > 1;
1976
1977   ##
1978   # insert
1979   ##
1980
1981   unless( $opt{testonly} ) {
1982     foreach my $cust_event ( @cust_event ) {
1983
1984       my $error = $cust_event->insert();
1985       if ( $error ) {
1986         $dbh->rollback if $oldAutoCommit;
1987         return $error;
1988       }
1989
1990     }
1991   }
1992
1993   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
1994
1995   ##
1996   # return
1997   ##
1998
1999   warn "  returning events: ". Dumper(@cust_event). "\n"
2000     if $DEBUG > 2;
2001
2002   \@cust_event;
2003
2004 }
2005
2006 =item apply_payments_and_credits [ OPTION => VALUE ... ]
2007
2008 Applies unapplied payments and credits.
2009
2010 In most cases, this new method should be used in place of sequential
2011 apply_payments and apply_credits methods.
2012
2013 A hash of optional arguments may be passed.  Currently "manual" is supported.
2014 If true, a payment receipt is sent instead of a statement when
2015 'payment_receipt_email' configuration option is set.
2016
2017 If there is an error, returns the error, otherwise returns false.
2018
2019 =cut
2020
2021 sub apply_payments_and_credits {
2022   my( $self, %options ) = @_;
2023
2024   local $SIG{HUP} = 'IGNORE';
2025   local $SIG{INT} = 'IGNORE';
2026   local $SIG{QUIT} = 'IGNORE';
2027   local $SIG{TERM} = 'IGNORE';
2028   local $SIG{TSTP} = 'IGNORE';
2029   local $SIG{PIPE} = 'IGNORE';
2030
2031   my $oldAutoCommit = $FS::UID::AutoCommit;
2032   local $FS::UID::AutoCommit = 0;
2033   my $dbh = dbh;
2034
2035   $self->select_for_update; #mutex
2036
2037   foreach my $cust_bill ( $self->open_cust_bill ) {
2038     my $error = $cust_bill->apply_payments_and_credits(%options);
2039     if ( $error ) {
2040       $dbh->rollback if $oldAutoCommit;
2041       return "Error applying: $error";
2042     }
2043   }
2044
2045   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
2046   ''; #no error
2047
2048 }
2049
2050 =item apply_credits OPTION => VALUE ...
2051
2052 Applies (see L<FS::cust_credit_bill>) unapplied credits (see L<FS::cust_credit>)
2053 to outstanding invoice balances in chronological order (or reverse
2054 chronological order if the I<order> option is set to B<newest>) and returns the
2055 value of any remaining unapplied credits available for refund (see
2056 L<FS::cust_refund>).
2057
2058 Dies if there is an error.
2059
2060 =cut
2061
2062 sub apply_credits {
2063   my $self = shift;
2064   my %opt = @_;
2065
2066   local $SIG{HUP} = 'IGNORE';
2067   local $SIG{INT} = 'IGNORE';
2068   local $SIG{QUIT} = 'IGNORE';
2069   local $SIG{TERM} = 'IGNORE';
2070   local $SIG{TSTP} = 'IGNORE';
2071   local $SIG{PIPE} = 'IGNORE';
2072
2073   my $oldAutoCommit = $FS::UID::AutoCommit;
2074   local $FS::UID::AutoCommit = 0;
2075   my $dbh = dbh;
2076
2077   $self->select_for_update; #mutex
2078
2079   unless ( $self->total_unapplied_credits ) {
2080     $dbh->commit or die $dbh->errstr if $oldAutoCommit;
2081     return 0;
2082   }
2083
2084   my @credits = sort { $b->_date <=> $a->_date} (grep { $_->credited > 0 }
2085       qsearch('cust_credit', { 'custnum' => $self->custnum } ) );
2086
2087   my @invoices = $self->open_cust_bill;
2088   @invoices = sort { $b->_date <=> $a->_date } @invoices
2089     if defined($opt{'order'}) && $opt{'order'} eq 'newest';
2090
2091   if ( $conf->exists('pkg-balances') ) {
2092     # limit @credits to those w/ a pkgnum grepped from $self
2093     my %pkgnums = ();
2094     foreach my $i (@invoices) {
2095       foreach my $li ( $i->cust_bill_pkg ) {
2096         $pkgnums{$li->pkgnum} = 1;
2097       }
2098     }
2099     @credits = grep { ! $_->pkgnum || $pkgnums{$_->pkgnum} } @credits;
2100   }
2101
2102   my $credit;
2103
2104   foreach my $cust_bill ( @invoices ) {
2105
2106     if ( !defined($credit) || $credit->credited == 0) {
2107       $credit = pop @credits or last;
2108     }
2109
2110     my $owed;
2111     if ( $conf->exists('pkg-balances') && $credit->pkgnum ) {
2112       $owed = $cust_bill->owed_pkgnum($credit->pkgnum);
2113     } else {
2114       $owed = $cust_bill->owed;
2115     }
2116     unless ( $owed > 0 ) {
2117       push @credits, $credit;
2118       next;
2119     }
2120
2121     my $amount = min( $credit->credited, $owed );
2122
2123     my $cust_credit_bill = new FS::cust_credit_bill ( {
2124       'crednum' => $credit->crednum,
2125       'invnum'  => $cust_bill->invnum,
2126       'amount'  => $amount,
2127     } );
2128     $cust_credit_bill->pkgnum( $credit->pkgnum )
2129       if $conf->exists('pkg-balances') && $credit->pkgnum;
2130     my $error = $cust_credit_bill->insert;
2131     if ( $error ) {
2132       $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
2133       die $error;
2134     }
2135
2136     redo if ($cust_bill->owed > 0) && ! $conf->exists('pkg-balances');
2137
2138   }
2139
2140   my $total_unapplied_credits = $self->total_unapplied_credits;
2141
2142   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
2143
2144   return $total_unapplied_credits;
2145 }
2146
2147 =item apply_payments  [ OPTION => VALUE ... ]
2148
2149 Applies (see L<FS::cust_bill_pay>) unapplied payments (see L<FS::cust_pay>)
2150 to outstanding invoice balances in chronological order.
2151
2152  #and returns the value of any remaining unapplied payments.
2153
2154 A hash of optional arguments may be passed.  Currently "manual" is supported.
2155 If true, a payment receipt is sent instead of a statement when
2156 'payment_receipt_email' configuration option is set.
2157
2158 Dies if there is an error.
2159
2160 =cut
2161
2162 sub apply_payments {
2163   my( $self, %options ) = @_;
2164
2165   local $SIG{HUP} = 'IGNORE';
2166   local $SIG{INT} = 'IGNORE';
2167   local $SIG{QUIT} = 'IGNORE';
2168   local $SIG{TERM} = 'IGNORE';
2169   local $SIG{TSTP} = 'IGNORE';
2170   local $SIG{PIPE} = 'IGNORE';
2171
2172   my $oldAutoCommit = $FS::UID::AutoCommit;
2173   local $FS::UID::AutoCommit = 0;
2174   my $dbh = dbh;
2175
2176   $self->select_for_update; #mutex
2177
2178   #return 0 unless
2179
2180   my @payments = sort { $b->_date <=> $a->_date }
2181                  grep { $_->unapplied > 0 }
2182                  $self->cust_pay;
2183
2184   my @invoices = sort { $a->_date <=> $b->_date}
2185                  grep { $_->owed > 0 }
2186                  $self->cust_bill;
2187
2188   if ( $conf->exists('pkg-balances') ) {
2189     # limit @payments to those w/ a pkgnum grepped from $self
2190     my %pkgnums = ();
2191     foreach my $i (@invoices) {
2192       foreach my $li ( $i->cust_bill_pkg ) {
2193         $pkgnums{$li->pkgnum} = 1;
2194       }
2195     }
2196     @payments = grep { ! $_->pkgnum || $pkgnums{$_->pkgnum} } @payments;
2197   }
2198
2199   my $payment;
2200
2201   foreach my $cust_bill ( @invoices ) {
2202
2203     if ( !defined($payment) || $payment->unapplied == 0 ) {
2204       $payment = pop @payments or last;
2205     }
2206
2207     my $owed;
2208     if ( $conf->exists('pkg-balances') && $payment->pkgnum ) {
2209       $owed = $cust_bill->owed_pkgnum($payment->pkgnum);
2210     } else {
2211       $owed = $cust_bill->owed;
2212     }
2213     unless ( $owed > 0 ) {
2214       push @payments, $payment;
2215       next;
2216     }
2217
2218     my $amount = min( $payment->unapplied, $owed );
2219
2220     my $cust_bill_pay = new FS::cust_bill_pay ( {
2221       'paynum' => $payment->paynum,
2222       'invnum' => $cust_bill->invnum,
2223       'amount' => $amount,
2224     } );
2225     $cust_bill_pay->pkgnum( $payment->pkgnum )
2226       if $conf->exists('pkg-balances') && $payment->pkgnum;
2227     my $error = $cust_bill_pay->insert(%options);
2228     if ( $error ) {
2229       $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
2230       die $error;
2231     }
2232
2233     redo if ( $cust_bill->owed > 0) && ! $conf->exists('pkg-balances');
2234
2235   }
2236
2237   my $total_unapplied_payments = $self->total_unapplied_payments;
2238
2239   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
2240
2241   return $total_unapplied_payments;
2242 }
2243
2244 =head1 BUGS
2245
2246 =head1 SEE ALSO
2247
2248 L<FS::cust_main>, L<FS::cust_main::Billing_Realtime>
2249
2250 =cut
2251
2252 1;