1 package FS::cust_credit;
4 use vars qw( @ISA $conf $unsuspendauto );
6 use FS::UID qw( dbh getotaker );
7 use FS::Misc qw(send_email);
8 use FS::Record qw( qsearch qsearchs );
9 use FS::cust_main_Mixin;
12 use FS::cust_credit_bill;
14 @ISA = qw( FS::cust_main_Mixin FS::Record );
16 #ask FS::UID to run this stuff for us later
17 $FS::UID::callback{'FS::cust_credit'} = sub {
20 $unsuspendauto = $conf->exists('unsuspendauto');
26 FS::cust_credit - Object methods for cust_credit records
32 $record = new FS::cust_credit \%hash;
33 $record = new FS::cust_credit { 'column' => 'value' };
35 $error = $record->insert;
37 $error = $new_record->replace($old_record);
39 $error = $record->delete;
41 $error = $record->check;
45 An FS::cust_credit object represents a credit; the equivalent of a negative
46 B<cust_bill> record (see L<FS::cust_bill>). FS::cust_credit inherits from
47 FS::Record. The following fields are currently supported:
51 =item crednum - primary key (assigned automatically for new credits)
53 =item custnum - customer (see L<FS::cust_main>)
55 =item amount - amount of the credit
57 =item _date - specified as a UNIX timestamp; see L<perlfunc/"time">. Also see
58 L<Time::Local> and L<Date::Parse> for conversion functions.
60 =item otaker - order taker (assigned automatically, see L<FS::UID>)
64 =item closed - books closed flag, empty or `Y'
74 Creates a new credit. To add the credit to the database, see L<"insert">.
78 sub table { 'cust_credit'; }
79 sub cust_linked { $_[0]->cust_main_custnum; }
80 sub cust_unlinked_msg {
82 "WARNING: can't find cust_main.custnum ". $self->custnum.
83 ' (cust_credit.crednum '. $self->crednum. ')';
88 Adds this credit to the database ("Posts" the credit). If there is an error,
89 returns the error, otherwise returns false.
96 local $SIG{HUP} = 'IGNORE';
97 local $SIG{INT} = 'IGNORE';
98 local $SIG{QUIT} = 'IGNORE';
99 local $SIG{TERM} = 'IGNORE';
100 local $SIG{TSTP} = 'IGNORE';
101 local $SIG{PIPE} = 'IGNORE';
103 my $oldAutoCommit = $FS::UID::AutoCommit;
104 local $FS::UID::AutoCommit = 0;
107 my $cust_main = qsearchs( 'cust_main', { 'custnum' => $self->custnum } );
108 my $old_balance = $cust_main->balance;
110 my $error = $self->SUPER::insert;
112 $dbh->rollback if $oldAutoCommit;
113 return "error inserting $self: $error";
116 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
118 #false laziness w/ cust_credit::insert
119 if ( $unsuspendauto && $old_balance && $cust_main->balance <= 0 ) {
120 my @errors = $cust_main->unsuspend;
122 # side-fx with nested transactions? upstack rolls back?
123 warn "WARNING:Errors unsuspending customer ". $cust_main->custnum. ": ".
129 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
137 Unless the closed flag is set, deletes this credit and all associated
138 applications (see L<FS::cust_credit_bill>). In most cases, you want to use
139 the void method instead to leave a record of the deleted credit.
143 # very similar to FS::cust_pay::delete
146 return "Can't delete closed credit" if $self->closed =~ /^Y/i;
148 local $SIG{HUP} = 'IGNORE';
149 local $SIG{INT} = 'IGNORE';
150 local $SIG{QUIT} = 'IGNORE';
151 local $SIG{TERM} = 'IGNORE';
152 local $SIG{TSTP} = 'IGNORE';
153 local $SIG{PIPE} = 'IGNORE';
155 my $oldAutoCommit = $FS::UID::AutoCommit;
156 local $FS::UID::AutoCommit = 0;
159 foreach my $cust_credit_bill ( $self->cust_credit_bill ) {
160 my $error = $cust_credit_bill->delete;
162 $dbh->rollback if $oldAutoCommit;
167 foreach my $cust_credit_refund ( $self->cust_credit_refund ) {
168 my $error = $cust_credit_refund->delete;
170 $dbh->rollback if $oldAutoCommit;
175 my $error = $self->SUPER::delete(@_);
177 $dbh->rollback if $oldAutoCommit;
181 if ( $conf->config('deletecredits') ne '' ) {
183 my $cust_main = $self->cust_main;
185 my $error = send_email(
186 'from' => $conf->config('invoice_from'), #??? well as good as any
187 'to' => $conf->config('deletecredits'),
188 'subject' => 'FREESIDE NOTIFICATION: Credit deleted',
190 "This is an automatic message from your Freeside installation\n",
191 "informing you that the following credit has been deleted:\n",
193 'crednum: '. $self->crednum. "\n",
194 'custnum: '. $self->custnum.
195 " (". $cust_main->last. ", ". $cust_main->first. ")\n",
196 'amount: $'. sprintf("%.2f", $self->amount). "\n",
197 'date: '. time2str("%a %b %e %T %Y", $self->_date). "\n",
198 'reason: '. $self->reason. "\n",
203 $dbh->rollback if $oldAutoCommit;
204 return "can't send credit deletion notification: $error";
209 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
215 =item replace OLD_RECORD
217 You can, but probably shouldn't modify credits...
222 #return "Can't modify credit!"
224 return "Can't modify closed credit" if $self->closed =~ /^Y/i;
225 $self->SUPER::replace(@_);
230 Checks all fields to make sure this is a valid credit. If there is an error,
231 returns the error, otherwise returns false. Called by the insert and replace
240 $self->ut_numbern('crednum')
241 || $self->ut_number('custnum')
242 || $self->ut_numbern('_date')
243 || $self->ut_money('amount')
244 || $self->ut_textn('reason')
245 || $self->ut_enum('closed', [ '', 'Y' ])
247 return $error if $error;
249 return "amount must be > 0 " if $self->amount <= 0;
251 return "Unknown customer"
252 unless qsearchs( 'cust_main', { 'custnum' => $self->custnum } );
254 $self->_date(time) unless $self->_date;
256 $self->otaker(getotaker);
263 Depreciated. See the cust_credit_refund method.
265 #Returns all refunds (see L<FS::cust_refund>) for this credit.
271 croak "FS::cust_credit->cust_pay depreciated; see ".
272 "FS::cust_credit->cust_credit_refund";
274 #sort { $a->_date <=> $b->_date }
275 # qsearch( 'cust_refund', { 'crednum' => $self->crednum } )
279 =item cust_credit_refund
281 Returns all refund applications (see L<FS::cust_credit_refund>) for this credit.
285 sub cust_credit_refund {
287 sort { $a->_date <=> $b->_date }
288 qsearch( 'cust_credit_refund', { 'crednum' => $self->crednum } )
292 =item cust_credit_bill
294 Returns all application to invoices (see L<FS::cust_credit_bill>) for this
299 sub cust_credit_bill {
301 sort { $a->_date <=> $b->_date }
302 qsearch( 'cust_credit_bill', { 'crednum' => $self->crednum } )
308 Returns the amount of this credit that is still outstanding; which is
309 amount minus all refund applications (see L<FS::cust_credit_refund>) and
310 applications to invoices (see L<FS::cust_credit_bill>).
316 my $amount = $self->amount;
317 $amount -= $_->amount foreach ( $self->cust_credit_refund );
318 $amount -= $_->amount foreach ( $self->cust_credit_bill );
319 sprintf( "%.2f", $amount );
324 Returns the customer (see L<FS::cust_main>) for this credit.
330 qsearchs( 'cust_main', { 'custnum' => $self->custnum } );
342 Returns an SQL fragment to retreive the unapplied amount.
351 ( SELECT SUM(amount) FROM cust_credit_refund
352 WHERE cust_credit.crednum = cust_credit_refund.crednum )
356 ( SELECT SUM(amount) FROM cust_credit_bill
357 WHERE cust_credit.crednum = cust_credit_bill.crednum )
368 The delete method. The replace method.
370 B<credited> and B<credited_sql> should probably be called B<unapplied> and
375 L<FS::Record>, L<FS::cust_credit_refund>, L<FS::cust_refund>,
376 L<FS::cust_credit_bill> L<FS::cust_bill>, schema.html from the base