htdocs/docs/man/FS/cust_main.html

   1 <HTML>
   2 <HEAD>
   3 <TITLE>FS::cust_main - Object methods for cust_main records</TITLE>
   4 <LINK REV="made" HREF="mailto:none">
   5 </HEAD>
   6
   7 <BODY>
   8
   9 <!-- INDEX BEGIN -->
  10
  11 <UL>
  12
  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>
  20 </UL>
  21 <!-- INDEX END -->
  22
  23 <HR>
  24 <P>
  25 <H1><A NAME="NAME">NAME</A></H1>
  26 <P>
  27 FS::cust_main - Object methods for cust_main records
  28
  29 <P>
  30 <HR>
  31 <H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
  32 <P>
  33 <PRE>  use FS::cust_main;
  34 </PRE>
  35 <P>
  36 <PRE>  $record = new FS::cust_main \%hash;
  37   $record = new FS::cust_main { 'column' =&gt; 'value' };
  38 </PRE>
  39 <P>
  40 <PRE>  $error = $record-&gt;insert;
  41 </PRE>
  42 <P>
  43 <PRE>  $error = $new_record-&gt;replace($old_record);
  44 </PRE>
  45 <P>
  46 <PRE>  $error = $record-&gt;delete;
  47 </PRE>
  48 <P>
  49 <PRE>  $error = $record-&gt;check;
  50 </PRE>
  51 <P>
  52 <PRE>  @cust_pkg = $record-&gt;all_pkgs;
  53 </PRE>
  54 <P>
  55 <PRE>  @cust_pkg = $record-&gt;ncancelled_pkgs;
  56 </PRE>
  57 <P>
  58 <PRE>  $error = $record-&gt;bill;
  59   $error = $record-&gt;bill %options;
  60   $error = $record-&gt;bill 'time' =&gt; $time;
  61 </PRE>
  62 <P>
  63 <PRE>  $error = $record-&gt;collect;
  64   $error = $record-&gt;collect %options;
  65   $error = $record-&gt;collect 'invoice_time'   =&gt; $time,
  66                             'batch_card'     =&gt; 'yes',
  67                             'report_badcard' =&gt; 'yes',
  68                           ;
  69 </PRE>
  70 <P>
  71 <HR>
  72 <H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
  73 <P>
  74 An FS::cust_main object represents a customer. FS::cust_main inherits from
  75 FS::Record. The following fields are currently supported:
  76
  77 <DL>
  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), `COMP' (free), or `PREPAY' (special billing type: applies a credit - see FS::prepay_credit and sets billing type to BILL)</A></STRONG><DD>
  96 <DT><STRONG><A NAME="item_payinfo">payinfo - card number, P.O., comp issuer (4-8 lowercase alphanumerics; think username) or prepayment identifier (see FS::prepay_credit)</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>
 101 </DL>
 102 <P>
 103 <HR>
 104 <H1><A NAME="METHODS">METHODS</A></H1>
 105 <DL>
 106 <DT><STRONG><A NAME="item_new">new HASHREF</A></STRONG><DD>
 107 <P>
 108 Creates a new customer. To add the customer to the database, see <A HREF="#insert">insert</A>.
 109
 110 <P>
 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.
 113
 114 <DT><STRONG><A NAME="item_insert">insert</A></STRONG><DD>
 115 <P>
 116 Adds this customer to the database. If there is an error, returns the
 117 error, otherwise returns false.
 118
 119 <DT><STRONG><A NAME="item_delete">delete NEW_CUSTNUM</A></STRONG><DD>
 120 <P>
 121 This deletes the customer. If there is an error, returns the error,
 122 otherwise returns false.
 123
 124 <P>
 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>).
 128
 129 <P>
 130 If the customer has any packages, you need to pass a new (valid) customer
 131 number for those packages to be transferred to.
 132
 133 <P>
 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>).
 135
 136 <DT><STRONG><A NAME="item_replace">replace OLD_RECORD</A></STRONG><DD>
 137 <P>
 138 Replaces the OLD_RECORD with this one in the database. If there is an
 139 error, returns the error, otherwise returns false.
 140
 141 <DT><STRONG><A NAME="item_check">check</A></STRONG><DD>
 142 <P>
 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
 145 and repalce methods.
 146
 147 <DT><STRONG><A NAME="item_all_pkgs">all_pkgs</A></STRONG><DD>
 148 <P>
 149 Returns all packages (see <A HREF="../FS/cust_pkg.html">FS::cust_pkg</A>) for this customer.
 150
 151 <DT><STRONG><A NAME="item_ncancelled_pkgs">ncancelled_pkgs</A></STRONG><DD>
 152 <P>
 153 Returns all non-cancelled packages (see <A HREF="../FS/cust_pkg.html">FS::cust_pkg</A>) for this customer.
 154
 155 <DT><STRONG><A NAME="item_bill">bill OPTIONS</A></STRONG><DD>
 156 <P>
 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.
 158
 159 <P>
 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.
 163
 164 <P>
 165 If there is an error, returns the error, otherwise returns false.
 166
 167 <DT><STRONG><A NAME="item_collect">collect OPTIONS</A></STRONG><DD>
 168 <P>
 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.
 171
 172 <P>
 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
 175 (`COMP').
 176
 177 <P>
 178 If there is an error, returns the error, otherwise returns false.
 179
 180 <P>
 181 Currently available options are:
 182
 183 <P>
 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.
 188
 189 <P>
 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.
 192
 193 <P>
 194 report_badcard - Set this true if you want bad card transactions to return
 195 an error. By default, they don't.
 196
 197 <DT><STRONG><A NAME="item_total_owed">total_owed</A></STRONG><DD>
 198 <P>
 199 Returns the total owed for this customer on all invoices (see <A HREF="../FS/cust_bill.html">FS::cust_bill</A>).
 200
 201 <DT><STRONG><A NAME="item_total_credited">total_credited</A></STRONG><DD>
 202 <P>
 203 Returns the total credits (see <A HREF="../FS/cust_credit.html">FS::cust_credit</A>) for this customer.
 204
 205 <DT><STRONG><A NAME="item_balance">balance</A></STRONG><DD>
 206 <P>
 207 Returns the balance for this customer (total owed minus total credited).
 208
 209 <DT><STRONG><A NAME="item_invoicing_list">invoicing_list [ ARRAYREF ]</A></STRONG><DD>
 210 <P>
 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.
 214
 215 <P>
 216 Returns a list of email addresses (with svcnum entries expanded).
 217
 218 <P>
 219 Note: You can clear the invoicing list by passing an empty ARRAYREF. You
 220 can check it without disturbing anything by passing nothing.
 221
 222 <P>
 223 This interface may change in the future.
 224
 225 <DT><STRONG><A NAME="item_check_invoicing_list">check_invoicing_list ARRAYREF</A></STRONG><DD>
 226 <P>
 227 Checks these arguements as valid input for the invoicing_list method. If
 228 there is an error, returns the error, otherwise returns false.
 229
 230 </DL>
 231 <P>
 232 <HR>
 233 <H1><A NAME="VERSION">VERSION</A></H1>
 234 <P>
 235 $Id: cust_main.html,v 1.2 2000-03-03 18:22:43 ivan Exp $
 236
 237 <P>
 238 <HR>
 239 <H1><A NAME="BUGS">BUGS</A></H1>
 240 <P>
 241 The delete method.
 242
 243 <P>
 244 The delete method should possibly take an FS::cust_main object reference
 245 instead of a scalar customer number.
 246
 247 <P>
 248 Bill and collect options should probably be passed as references instead of
 249 a list.
 250
 251 <P>
 252 CyberCash v2 forces us to define some variables in package main.
 253
 254 <P>
 255 There should probably be a configuration file with a list of allowed credit
 256 card types.
 257
 258 <P>
 259 CyberCash is the only processor.
 260
 261 <P>
 262 No multiple currency support (probably a larger project than just this
 263 module).
 264
 265 <P>
 266 <HR>
 267 <H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
 268 <P>
 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>
 270
 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.
 274
 275 </BODY>
 276
 277 </HTML>