*sigh*
[freeside.git] / FS / FS / cust_credit.pm
1 package FS::cust_credit;
2
3 use strict;
4 use vars qw( @ISA );
5 use FS::UID qw( getotaker );
6 use FS::Record qw( qsearchs );
7 use FS::cust_main;
8 use FS::cust_refund;
9
10 @ISA = qw( FS::Record );
11
12 =head1 NAME
13
14 FS::cust_credit - Object methods for cust_credit records
15
16 =head1 SYNOPSIS
17
18   use FS::cust_credit;
19
20   $record = new FS::cust_credit \%hash;
21   $record = new FS::cust_credit { 'column' => 'value' };
22
23   $error = $record->insert;
24
25   $error = $new_record->replace($old_record);
26
27   $error = $record->delete;
28
29   $error = $record->check;
30
31 =head1 DESCRIPTION
32
33 An FS::cust_credit object represents a credit; the equivalent of a negative
34 B<cust_bill> record (see L<FS::cust_bill>).  FS::cust_credit inherits from
35 FS::Record.  The following fields are currently supported:
36
37 =over 4
38
39 =item crednum - primary key (assigned automatically for new credits)
40
41 =item custnum - customer (see L<FS::cust_main>)
42
43 =item amount - amount of the credit
44
45 =item _date - specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
46 L<Time::Local> and L<Date::Parse> for conversion functions.
47
48 =item otaker - order taker (assigned automatically, see L<FS::UID>)
49
50 =item reason - text
51
52 =back
53
54 =head1 METHODS
55
56 =over 4
57
58 =item new HASHREF
59
60 Creates a new credit.  To add the credit to the database, see L<"insert">.
61
62 =cut
63
64 sub table { 'cust_credit'; }
65
66 =item insert
67
68 Adds this credit to the database ("Posts" the credit).  If there is an error,
69 returns the error, otherwise returns false.
70
71 =item delete
72
73 Currently unimplemented.
74
75 =cut
76
77 sub delete {
78   return "Can't remove credit!"
79 }
80
81 =item replace OLD_RECORD
82
83 Credits may not be modified; there would then be no record the credit was ever
84 posted.
85
86 =cut
87
88 sub replace {
89   return "Can't modify credit!"
90 }
91
92 =item check
93
94 Checks all fields to make sure this is a valid credit.  If there is an error,
95 returns the error, otherwise returns false.  Called by the insert and replace
96 methods.
97
98 =cut
99
100 sub check {
101   my $self = shift;
102
103   my $error =
104     $self->ut_numbern('crednum')
105     || $self->ut_number('custnum')
106     || $self->ut_numbern('_date')
107     || $self->ut_money('amount')
108     || $self->ut_textn('reason');
109   ;
110   return $error if $error;
111
112   return "Unknown customer"
113     unless qsearchs( 'cust_main', { 'custnum' => $self->custnum } );
114
115   $self->_date(time) unless $self->_date;
116
117   $self->otaker(getotaker);
118
119   ''; #no error
120 }
121
122 =item cust_refund
123
124 Returns all refunds (see L<FS::cust_refund>) for this credit.
125
126 =cut
127
128 sub cust_refund {
129   my $self = shift;
130   sort { $a->_date <=> $b->_date }
131     qsearch( 'cust_refund', { 'crednum' => $self->crednum } )
132   ;
133 }
134
135 =item credited
136
137 Returns the amount of this credit that is still outstanding; which is
138 amount minus all refunds (see L<FS::cust_refund>).
139
140 =cut
141
142 sub credited {
143   my $self = shift;
144   my $amount = $self->amount;
145   $amount -= $_->refund foreach ( $self->cust_refund );
146   $amount;
147 }
148
149 =back
150
151 =head1 VERSION
152
153 $Id: cust_credit.pm,v 1.5 2001-04-23 19:27:28 ivan Exp $
154
155 =head1 BUGS
156
157 The delete method.
158
159 =head1 SEE ALSO
160
161 L<FS::Record>, L<FS::cust_refund>, L<FS::cust_bill>, schema.html from the base
162 documentation.
163
164 =cut
165
166 1;
167