3 <TITLE>FS::cust_main - Object methods for cust_main records</TITLE>
4 <LINK REV="made" HREF="mailto:ivan@rootwood.sisd.com">
13 <LI><A HREF="#NAME">NAME</A>
14 <LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
15 <LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
16 <LI><A HREF="#METHODS">METHODS</A>
17 <LI><A HREF="#VERSION">VERSION</A>
18 <LI><A HREF="#BUGS">BUGS</A>
19 <LI><A HREF="#SEE_ALSO">SEE ALSO</A>
25 <H1><A NAME="NAME">NAME</A></H1>
27 FS::cust_main - Object methods for cust_main records
31 <H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
33 <PRE> use FS::cust_main;
36 <PRE> $record = new FS::cust_main \%hash;
37 $record = new FS::cust_main { 'column' => 'value' };
40 <PRE> $error = $record->insert;
43 <PRE> $error = $new_record->replace($old_record);
46 <PRE> $error = $record->delete;
49 <PRE> $error = $record->check;
52 <PRE> @cust_pkg = $record->all_pkgs;
55 <PRE> @cust_pkg = $record->ncancelled_pkgs;
58 <PRE> $error = $record->bill;
59 $error = $record->bill %options;
60 $error = $record->bill 'time' => $time;
63 <PRE> $error = $record->collect;
64 $error = $record->collect %options;
65 $error = $record->collect 'invoice_time' => $time,
66 'batch_card' => 'yes',
67 'report_badcard' => 'yes',
72 <H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
74 An FS::cust_main object represents a customer. FS::cust_main inherits from
75 FS::Record. The following fields are currently supported:
78 <DT><STRONG><A NAME="item_custnum">custnum - primary key (assigned automatically for new customers)</A></STRONG><DD>
79 <DT><STRONG><A NAME="item_agentnum">agentnum - agent (see FS::agent)</A></STRONG><DD>
80 <DT><STRONG><A NAME="item_refnum">refnum - referral (see FS::part_referral)</A></STRONG><DD>
81 <DT><STRONG><A NAME="item_first">first - name</A></STRONG><DD>
82 <DT><STRONG><A NAME="item_last">last - name</A></STRONG><DD>
83 <DT><STRONG><A NAME="item_ss">ss - social security number (optional)</A></STRONG><DD>
84 <DT><STRONG><A NAME="item_company">company - (optional)</A></STRONG><DD>
85 <DT><STRONG><A NAME="item_address1">address1</A></STRONG><DD>
86 <DT><STRONG><A NAME="item_address2">address2 - (optional)</A></STRONG><DD>
87 <DT><STRONG><A NAME="item_city">city</A></STRONG><DD>
88 <DT><STRONG><A NAME="item_county">county - (optional, see FS::cust_main_county)</A></STRONG><DD>
89 <DT><STRONG><A NAME="item_state">state - (see FS::cust_main_county)</A></STRONG><DD>
90 <DT><STRONG><A NAME="item_zip">zip</A></STRONG><DD>
91 <DT><STRONG><A NAME="item_country">country - (see FS::cust_main_county)</A></STRONG><DD>
92 <DT><STRONG><A NAME="item_daytime">daytime - phone (optional)</A></STRONG><DD>
93 <DT><STRONG><A NAME="item_night">night - phone (optional)</A></STRONG><DD>
94 <DT><STRONG><A NAME="item_fax">fax - phone (optional)</A></STRONG><DD>
95 <DT><STRONG><A NAME="item_payby">payby - `CARD' (credit cards), `BILL' (billing), or `COMP' (free)</A></STRONG><DD>
96 <DT><STRONG><A NAME="item_payinfo">payinfo - card number, P.O.#, or comp issuer (4-8 lowercase alphanumerics; think username)</A></STRONG><DD>
97 <DT><STRONG><A NAME="item_paydate">paydate - expiration date, mm/yyyy, m/yyyy, mm/yy or m/yy</A></STRONG><DD>
98 <DT><STRONG><A NAME="item_payname">payname - name on card or billing name</A></STRONG><DD>
99 <DT><STRONG><A NAME="item_tax">tax - tax exempt, empty or `Y'</A></STRONG><DD>
100 <DT><STRONG><A NAME="item_otaker">otaker - order taker (assigned automatically, see FS::UID)</A></STRONG><DD>
104 <H1><A NAME="METHODS">METHODS</A></H1>
106 <DT><STRONG><A NAME="item_new">new HASHREF</A></STRONG><DD>
108 Creates a new customer. To add the customer to the database, see <A HREF="#insert">insert</A>.
111 Note that this stores the hash reference, not a distinct copy of the hash
112 it points to. You can ask the object for a copy with the <EM>hash</EM> method.
114 <DT><STRONG><A NAME="item_insert">insert</A></STRONG><DD>
116 Adds this customer to the database. If there is an error, returns the
117 error, otherwise returns false.
119 <DT><STRONG><A NAME="item_delete">delete NEW_CUSTNUM</A></STRONG><DD>
121 This deletes the customer. If there is an error, returns the error,
122 otherwise returns false.
125 This will completely remove all traces of the customer record. This is not
126 what you want when a customer cancels service; for that, cancel all of the
127 customer's packages (see <A HREF="../FS/cust_pkg.html#cancel">cancel</A>).
130 If the customer has any packages, you need to pass a new (valid) customer
131 number for those packages to be transferred to.
134 You can't delete a customer with invoices (see <A HREF="../FS/cust_bill.html">FS::cust_bill</A>), or credits (see <A HREF="../FS/cust_credit.html">FS::cust_credit</A>).
136 <DT><STRONG><A NAME="item_replace">replace OLD_RECORD</A></STRONG><DD>
138 Replaces the OLD_RECORD with this one in the database. If there is an
139 error, returns the error, otherwise returns false.
141 <DT><STRONG><A NAME="item_check">check</A></STRONG><DD>
143 Checks all fields to make sure this is a valid customer record. If there is
144 an error, returns the error, otherwise returns false. Called by the insert
147 <DT><STRONG><A NAME="item_all_pkgs">all_pkgs</A></STRONG><DD>
149 Returns all packages (see <A HREF="../FS/cust_pkg.html">FS::cust_pkg</A>) for this customer.
151 <DT><STRONG><A NAME="item_ncancelled_pkgs">ncancelled_pkgs</A></STRONG><DD>
153 Returns all non-cancelled packages (see <A HREF="../FS/cust_pkg.html">FS::cust_pkg</A>) for this customer.
155 <DT><STRONG><A NAME="item_bill">bill OPTIONS</A></STRONG><DD>
157 Generates invoices (see <A HREF="../FS/cust_bill.html">FS::cust_bill</A>) for this customer. Usually used in conjunction with the collect method.
160 The only currently available option is `time', which bills the customer as
161 if it were that time. It is specified as a UNIX timestamp; see
162 <EM>perlfunc</EM>). Also see <A HREF="../Time/Local.html">Time::Local</A> and <A HREF="../Date/Parse.html">Date::Parse</A> for conversion functions.
165 If there is an error, returns the error, otherwise returns false.
167 <DT><STRONG><A NAME="item_collect">collect OPTIONS</A></STRONG><DD>
169 (Attempt to) collect money for this customer's outstanding invoices (see
170 <A HREF="../FS/cust_bill.html">FS::cust_bill</A>). Usually used after the bill method.
173 Depending on the value of `payby', this may print an invoice (`BILL'),
174 charge a credit card (`CARD'), or just add any necessary (pseudo-)payment
178 If there is an error, returns the error, otherwise returns false.
181 Currently available options are:
184 invoice_time - Use this time when deciding when to print invoices and late
185 notices on those invoices. The default is now. It is specified as a UNIX
186 timestamp; see <EM>perlfunc</EM>). Also see <A HREF="../Time/Local.html">Time::Local</A> and <A HREF="../Date/Parse.html">Date::Parse</A>
187 for conversion functions.
190 batch_card - Set this true to batch cards (see <A HREF=".././FS/cust_pay_batch.html#">the cust_pay_batch manpage</A>). By default, cards are processed immediately, which will generate an
191 error if CyberCash is not installed.
194 report_badcard - Set this true if you want bad card transactions to return
195 an error. By default, they don't.
197 <DT><STRONG><A NAME="item_total_owed">total_owed</A></STRONG><DD>
199 Returns the total owed for this customer on all invoices (see <A HREF="../FS/cust_bill.html">FS::cust_bill</A>).
201 <DT><STRONG><A NAME="item_total_credited">total_credited</A></STRONG><DD>
203 Returns the total credits (see <A HREF="../FS/cust_credit.html">FS::cust_credit</A>) for this customer.
205 <DT><STRONG><A NAME="item_balance">balance</A></STRONG><DD>
207 Returns the balance for this customer (total owed minus total credited).
209 <DT><STRONG><A NAME="item_invoicing_list">invoicing_list [ ARRAYREF ]</A></STRONG><DD>
211 If an arguement is given, sets these email addresses as invoice recipients
212 (see <A HREF="../FS/cust_main_invoice.html">FS::cust_main_invoice</A>). Errors are not fatal and are not reported (except as warnings), so use
213 check_invoicing_list first.
216 Returns a list of email addresses (with svcnum entries expanded).
219 Note: You can clear the invoicing list by passing an empty ARRAYREF. You
220 can check it without disturbing anything by passing nothing.
223 This interface may change in the future.
225 <DT><STRONG><A NAME="item_check_invoicing_list">check_invoicing_list ARRAYREF</A></STRONG><DD>
227 Checks these arguements as valid input for the invoicing_list method. If
228 there is an error, returns the error, otherwise returns false.
233 <H1><A NAME="VERSION">VERSION</A></H1>
235 $Id: cust_main.html,v 1.1 1999-08-04 12:13:27 ivan Exp $
239 <H1><A NAME="BUGS">BUGS</A></H1>
244 The delete method should possibly take an FS::cust_main object reference
245 instead of a scalar customer number.
248 Bill and collect options should probably be passed as references instead of
252 CyberCash v2 forces us to define some variables in package main.
255 There should probably be a configuration file with a list of allowed credit
259 CyberCash is the only processor.
262 No multiple currency support (probably a larger project than just this
267 <H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
269 <A HREF="../FS/Record.html">FS::Record</A>, <A HREF="../FS/cust_pkg.html">FS::cust_pkg</A>, <A HREF="../FS/cust_bill.html">FS::cust_bill</A>, <A HREF="../FS/cust_credit.html">FS::cust_credit</A>
271 <A HREF="../FS/cust_pay_batch.html">FS::cust_pay_batch</A>, <A HREF="../FS/agent.html">FS::agent</A>, <A HREF="../FS/part_referral.html">FS::part_referral</A>,
272 <A HREF="../FS/cust_main_county.html">FS::cust_main_county</A>, <A HREF="../FS/cust_main_invoice.html">FS::cust_main_invoice</A>,
273 <A HREF="../FS/UID.html">FS::UID</A>, schema.html from the base documentation.