htdocs/docs/man/cust_main.txt

   1 NAME
   2     FS::cust_main - Object methods for cust_main records
   3
   4 SYNOPSIS
   5       use FS::cust_main;
   6
   7       $record = create FS::cust_main \%hash;
   8       $record = create FS::cust_main { 'column' => 'value' };
   9
  10       $error = $record->insert;
  11
  12       $error = $new_record->replace($old_record);
  13
  14       $error = $record->delete;
  15
  16       $error = $record->check;
  17
  18       @cust_pkg = $record->all_pkgs;
  19
  20       @cust_pkg = $record->ncancelled_pkgs;
  21
  22       $error = $record->bill;
  23       $error = $record->bill %options;
  24       $error = $record->bill 'time' => $time;
  25
  26       $error = $record->collect;
  27       $error = $record->collect %options;
  28       $error = $record->collect 'invoice_time'   => $time,
  29                                 'batch_card'     => 'yes',
  30                                 'report_badcard' => 'yes',
  31                               ;
  32
  33 DESCRIPTION
  34     An FS::cust_main object represents a customer. FS::cust_main
  35     inherits from FS::Record. The following fields are currently
  36     supported:
  37
  38     custnum - primary key (assigned automatically for new customers)
  39     agentnum - agent (see the FS::agent manpage)
  40     refnum - referral (see the FS::part_referral manpage)
  41     first - name
  42     last - name
  43     ss - social security number (optional)
  44     company - (optional)
  45     address1
  46     address2 - (optional)
  47     city
  48     county - (optional, see the FS::cust_main_county manpage)
  49     state - (see the FS::cust_main_county manpage)
  50     zip
  51     country - (see the FS::cust_main_county manpage)
  52     daytime - phone (optional)
  53     night - phone (optional)
  54     payby - `CARD' (credit cards), `BILL' (billing), or `COMP' (free)
  55     payinfo - card number, P.O.#, or comp issuer (4-8 lowercase alphanumerics; think username)
  56     paydate - expiration date, mm/yyyy, m/yyyy, mm/yy or m/yy
  57     payname - name on card or billing name
  58     tax - tax exempt, empty or `Y'
  59     otaker - order taker (assigned automatically, see the FS::UID manpage)
  60 METHODS
  61     create HASHREF
  62         Creates a new customer. To add the customer to the database,
  63         see the section on "insert".
  64
  65         Note that this stores the hash reference, not a distinct
  66         copy of the hash it points to. You can ask the object for a
  67         copy with the *hash* method.
  68
  69     insert
  70         Adds this customer to the database. If there is an error,
  71         returns the error, otherwise returns false.
  72
  73     delete
  74         Currently unimplemented. Maybe cancel all of this customer's
  75         packages (cust_pkg)?
  76
  77         I don't remove the customer record in the database because
  78         there would then be no record the customer ever existed
  79         (which is bad, no?)
  80
  81     replace OLD_RECORD
  82         Replaces the OLD_RECORD with this one in the database. If
  83         there is an error, returns the error, otherwise returns
  84         false.
  85
  86     check
  87         Checks all fields to make sure this is a valid customer
  88         record. If there is an error, returns the error, otherwise
  89         returns false. Called by the insert and repalce methods.
  90
  91     all_pkgs
  92         Returns all packages (see the FS::cust_pkg manpage) for this
  93         customer.
  94
  95     ncancelled_pkgs
  96         Returns all non-cancelled packages (see the FS::cust_pkg
  97         manpage) for this customer.
  98
  99     bill OPTIONS
 100         Generates invoices (see the FS::cust_bill manpage) for this
 101         customer. Usually used in conjunction with the collect
 102         method.
 103
 104         The only currently available option is `time', which bills
 105         the customer as if it were that time. It is specified as a
 106         UNIX timestamp; see the section on "time" in the perlfunc
 107         manpage). Also see the Time::Local manpage and the
 108         Date::Parse manpage for conversion functions.
 109
 110         If there is an error, returns the error, otherwise returns
 111         false.
 112
 113     collect OPTIONS
 114         (Attempt to) collect money for this customer's outstanding
 115         invoices (see the FS::cust_bill manpage). Usually used after
 116         the bill method.
 117
 118         Depending on the value of `payby', this may print an invoice
 119         (`BILL'), charge a credit card (`CARD'), or just add any
 120         necessary (pseudo-)payment (`COMP').
 121
 122         If there is an error, returns the error, otherwise returns
 123         false.
 124
 125         Currently available options are:
 126
 127         invoice_time - Use this time when deciding when to print
 128         invoices and late notices on those invoices. The default is
 129         now. It is specified as a UNIX timestamp; see the section on
 130         "time" in the perlfunc manpage). Also see the Time::Local
 131         manpage and the Date::Parse manpage for conversion
 132         functions.
 133
 134         batch_card - Set this true to batch cards (see the
 135         cust_pay_batch manpage). By default, cards are processed
 136         immediately, which will generate an error if CyberCash is
 137         not installed.
 138
 139         report_badcard - Set this true if you want bad card
 140         transactions to return an error. By default, they don't.
 141
 142     total_owed
 143         Returns the total owed for this customer on all invoices
 144         (see the FS::cust_bill manpage).
 145
 146     total_credited
 147         Returns the total credits (see the FS::cust_credit manpage)
 148         for this customer.
 149
 150     balance
 151         Returns the balance for this customer (total owed minus
 152         total credited).
 153
 154 BUGS
 155     The delete method.
 156
 157     It doesn't properly override FS::Record yet.
 158
 159     hfields should be removed.
 160
 161     Bill and collect options should probably be passed as references
 162     instead of a list.
 163
 164     CyberCash v2 forces us to define some variables in package main.
 165
 166 SEE ALSO
 167     the FS::Record manpage, the FS::cust_pkg manpage, the
 168     FS::cust_bill manpage, the FS::cust_credit manpage the
 169     FS::cust_pay_batch manpage, the FS::agent manpage, the
 170     FS::part_referral manpage, the FS::cust_main_county manpage, the
 171     FS::UID manpage, schema.html from the base documentation.
 172
 173 HISTORY
 174     ivan@voicenet.com 97-jul-28
 175
 176     Changed to standard Business::CreditCard no more TableUtil
 177     EXPORT_OK FS::Record's hfields removed unique calls and locking
 178     (not needed here now) wrapped the (now) optional fields in if
 179     statements in sub check (notyetdone!) ivan@sisd.com 97-nov-12
 180
 181     updated paydate with SQL-type date info ivan@sisd.com 98-mar-5
 182
 183     Added export of datasrc from UID.pm for Pg6.3 changed 'day' to
 184     'daytime' because Pg6.3 reserves the day word
 185     bmccane@maxbaud.net 98-apr-3
 186
 187     in ->create, s/svc_acct/cust_main/, now it should actually
 188     eliminate the warnings it was meant to ivan@sisd.com 98-jul-16
 189
 190     don't require a phone number and allow '/' in company names
 191     ivan@sisd.com 98-jul-18
 192
 193     use ut_ and rewrite &check, &*_pkgs ivan@sisd.com 98-sep-5
 194
 195     pod, merge with FS::Bill (about time!), total_owed,
 196     total_credited and balance methods, cleaned collect method,
 197     source modifications no longer necessary to enable cybercash,
 198     cybercash v3 support, don't need to import
 199     FS::UID::{datasrc,checkruid} ivan@sisd.com 98-sep-19-21
 200