Difference between revisions of "Freeside:1.9:Documentation:Developer/FS/cust main"

From Freeside
Jump to: navigation, search
(import from POD)
m (Edit via perl MediaWiki framework (1.13))
 
(2 intermediate revisions by the same user not shown)
Line 35: Line 35:
 
An FS::cust_main object represents a customer. FS::cust_main inherits from FS::Record. The following fields are currently supported:
 
An FS::cust_main object represents a customer. FS::cust_main inherits from FS::Record. The following fields are currently supported:
  
; custnum - primary key (assigned automatically for new customers); agentnum - agent (see [[Freeside:1.9:Documentation:Developer/FS/agent|FS::agent]]); refnum - Advertising source (see [[Freeside:1.9:Documentation:Developer/FS/part referral|FS::part_referral]]); first - name; last - name; ss - social security number (optional); company - (optional); address1; address2 - (optional); city; county - (optional, see [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]]); state - (see [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]]); zip; country - (see [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]]); daytime - phone (optional); night - phone (optional); fax - phone (optional); ship_first - name; ship_last - name; ship_company - (optional); ship_address1; ship_address2 - (optional); ship_city; ship_county - (optional, see [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]]); ship_state - (see [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]]); ship_zip; ship_country - (see [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]]); ship_daytime - phone (optional); ship_night - phone (optional); ship_fax - phone (optional); payby - Payment Type (See [[Freeside:1.9:Documentation:Developer/FS/payinfo Mixin|FS::payinfo_Mixin]] for valid payby values); payinfo - Payment Information (See [[Freeside:1.9:Documentation:Developer/FS/payinfo Mixin|FS::payinfo_Mixin]] for data format); paymask - Masked payinfo (See [[Freeside:1.9:Documentation:Developer/FS/payinfo Mixin|FS::payinfo_Mixin]] for how this works); paycvv
+
; custnum
 +
:Primary key (assigned automatically for new customers)
 +
; agentnum
 +
:Agent (see [[Freeside:1.9:Documentation:Developer/FS/agent|FS::agent]])
 +
; refnum
 +
:Advertising source (see [[Freeside:1.9:Documentation:Developer/FS/part referral|FS::part_referral]])
 +
; first
 +
:First name
 +
; last
 +
:Last name
 +
; ss
 +
:Cocial security number (optional)
 +
; company
 +
:(optional)
 +
; address1; address2
 +
:(optional)
 +
; city; county
 +
:(optional, see [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]])
 +
; state
 +
:(see [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]])
 +
; zip; country
 +
:(see [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]])
 +
; daytime
 +
:phone (optional)
 +
; night
 +
:phone (optional)
 +
; fax
 +
:phone (optional)
 +
; ship_first
 +
:Shipping first name
 +
; ship_last
 +
:Shipping last name
 +
; ship_company
 +
:(optional)
 +
; ship_address1; ship_address2
 +
:(optional)
 +
; ship_city; ship_county
 +
:(optional, see [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]])
 +
; ship_state
 +
:(see [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]])
 +
; ship_zip; ship_country
 +
:(see [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]])
 +
; ship_daytime
 +
:phone (optional)
 +
; ship_night
 +
:phone (optional)
 +
; ship_fax
 +
:phone (optional)
 +
; payby
 +
:Payment Type (See [[Freeside:1.9:Documentation:Developer/FS/payinfo Mixin|FS::payinfo_Mixin]] for valid payby values)
 +
; payinfo
 +
:Payment Information (See [[Freeside:1.9:Documentation:Developer/FS/payinfo Mixin|FS::payinfo_Mixin]] for data format)
 +
; paymask
 +
:Masked payinfo (See [[Freeside:1.9:Documentation:Developer/FS/payinfo Mixin|FS::payinfo_Mixin]] for how this works)
 +
; paycvv
 
:Card Verification Value, "CVV2" (also known as CVC2 or CID), the 3 or 4 digit number on the back (or front, for American Express) of the credit card
 
:Card Verification Value, "CVV2" (also known as CVC2 or CID), the 3 or 4 digit number on the back (or front, for American Express) of the credit card
; paydate - expiration date, mm/yyyy, m/yyyy, mm/yy or m/yy; paystart_month - start date month (maestro/solo cards only); paystart_year - start date year (maestro/solo cards only); payissue - issue number (maestro/solo cards only); payname - name on card or billing name; payip - IP address from which payment information was received; tax - tax exempt, empty or `Y'; otaker - order taker (assigned automatically, see [[Freeside:1.9:Documentation:Developer/FS/UID|FS::UID]]); comments - comments (optional); referral_custnum - referring customer number; spool_cdr - Enable individual CDR spooling, empty or `Y'
+
; paydate
 +
:Expiration date, mm/yyyy, m/yyyy, mm/yy or m/yy
 +
; paystart_month
 +
:Start date month (maestro/solo cards only)
 +
; paystart_year
 +
:Start date year (maestro/solo cards only)
 +
; payissue
 +
:Issue number (maestro/solo cards only)
 +
; payname
 +
:Name on card or billing name
 +
; payip
 +
:IP address from which payment information was received
 +
; tax
 +
:Tax exempt, empty or `Y'
 +
; otaker
 +
:Order taker (assigned automatically, see [[Freeside:1.9:Documentation:Developer/FS/UID|FS::UID]])
 +
; comments
 +
:Comments (optional)
 +
; referral_custnum
 +
:Referring customer number
 +
; spool_cdr
 +
:Enable individual CDR spooling, empty or `Y'
 +
; dundate
 +
:A suggestion to events (see [[Freeside:1.9:Documentation:Developer/FS/part bill event"|FS::part_bill_event"]]) to delay until this unix timestamp
 +
; squelch_cdr
 +
:Discourage individual CDR printing, empty or `Y'
 +
 
 
==METHODS==
 
==METHODS==
 
; new HASHREF
 
; new HASHREF
Line 67: Line 147:
  
 
:The ''noexport'' option is deprecated. If ''noexport'' is set true, no provisioning jobs (exports) are scheduled. (You can schedule them later with the '''reexport''' method.)
 
:The ''noexport'' option is deprecated. If ''noexport'' is set true, no provisioning jobs (exports) are scheduled. (You can schedule them later with the '''reexport''' method.)
 +
; order_pkg HASHREF | OPTION => VALUE ...
 +
:Orders a single package.
 +
 +
:Options may be passed as a list of key/value pairs or as a hash reference. Options are:
 +
:; cust_pkg
 +
::FS::cust_pkg object
 +
:; cust_location
 +
::Optional FS::cust_location object
 +
:; svcs
 +
::Optional arryaref of FS::svc_* service objects.
 +
:; depend_jobnum
 +
::If this option is set to a job queue jobnum (see [[Freeside:1.9:Documentation:Developer/FS/queue|FS::queue]]), all provisioning jobs will have a dependancy on the supplied job (they will not run until the specific job completes). This can be used to defer provisioning until some action completes (such as running the customer's credit card successfully).
 
; order_pkgs HASHREF, [ SECONDSREF, [ , OPTION => VALUE ... ] ]
 
; order_pkgs HASHREF, [ SECONDSREF, [ , OPTION => VALUE ... ] ]
:Like the insert method on an existing record, this method orders a package and included services atomicaly. Pass a Tie::RefHash data structure to this method containing FS::cust_pkg and FS::svc_''tablename'' objects. There should be a better explanation of this, but until then, here's an example:
+
:Like the insert method on an existing record, this method orders multiple packages and included services atomicaly. Pass a Tie::RefHash data structure to this method containing FS::cust_pkg and FS::svc_''tablename'' objects. There should be a better explanation of this, but until then, here's an example:
 
<code>
 
<code>
 
   use Tie::RefHash;
 
   use Tie::RefHash;
Line 126: Line 218:
  
 
:You can't delete a customer with invoices (see [[Freeside:1.9:Documentation:Developer/FS/cust bill|FS::cust_bill]]), or credits (see [[Freeside:1.9:Documentation:Developer/FS/cust credit|FS::cust_credit]]), payments (see [[Freeside:1.9:Documentation:Developer/FS/cust pay|FS::cust_pay]]) or refunds (see [[Freeside:1.9:Documentation:Developer/FS/cust refund|FS::cust_refund]]).
 
:You can't delete a customer with invoices (see [[Freeside:1.9:Documentation:Developer/FS/cust bill|FS::cust_bill]]), or credits (see [[Freeside:1.9:Documentation:Developer/FS/cust credit|FS::cust_credit]]), payments (see [[Freeside:1.9:Documentation:Developer/FS/cust pay|FS::cust_pay]]) or refunds (see [[Freeside:1.9:Documentation:Developer/FS/cust refund|FS::cust_refund]]).
; replace OLD_RECORD [ INVOICING_LIST_ARYREF ]
+
; replace [ OLD_RECORD ] [ INVOICING_LIST_ARYREF ]
 
:Replaces the OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
 
:Replaces the OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
  
Line 137: Line 229:
 
; check
 
; check
 
:Checks all fields to make sure this is a valid customer record. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
 
:Checks all fields to make sure this is a valid customer record. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
 +
; addr_fields
 +
:Returns a list of fields which have ship_ duplicates.
 +
; has_ship_address
 +
:Returns true if this customer record has a separate shipping address.
 
; all_pkgs
 
; all_pkgs
 
:Returns all packages (see [[Freeside:1.9:Documentation:Developer/FS/cust pkg|FS::cust_pkg]]) for this customer.
 
:Returns all packages (see [[Freeside:1.9:Documentation:Developer/FS/cust pkg|FS::cust_pkg]]) for this customer.
 
; cust_pkg
 
; cust_pkg
 
:Synonym for '''all_pkgs'''.
 
:Synonym for '''all_pkgs'''.
 +
; cust_location
 +
:Returns all locations (see [[Freeside:1.9:Documentation:Developer/FS/cust location|FS::cust_location]]) for this customer.
 
; ncancelled_pkgs
 
; ncancelled_pkgs
 
:Returns all non-cancelled packages (see [[Freeside:1.9:Documentation:Developer/FS/cust pkg|FS::cust_pkg]]) for this customer.
 
:Returns all non-cancelled packages (see [[Freeside:1.9:Documentation:Developer/FS/cust pkg|FS::cust_pkg]]) for this customer.
Line 181: Line 279:
  
 
:Options are passed as name-value pairs. Currently available options are:
 
:Options are passed as name-value pairs. Currently available options are:
:; time - bills the customer as if it were that time. Specified as a UNIX timestamp; see [[perlfunc#time|"time" in perlfunc]]). Also see [[Freeside:1.9:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:1.9:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions. For example&#58;<code>
+
:; time
 +
::Bills the customer as if it were that time. Specified as a UNIX timestamp; see [[perlfunc#time|"time" in perlfunc]]). Also see [[Freeside:1.9:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:1.9:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions. For example:
 +
<code>
 
  use Date::Parse;
 
  use Date::Parse;
 
  ...
 
  ...
 
  $cust_main->bill( 'time' => str2time('April 20th, 2001') );
 
  $cust_main->bill( 'time' => str2time('April 20th, 2001') );
 
</code>
 
</code>
:; invoice_time - used in conjunction with the ''time'' option, this option specifies the date of for the generated invoices. Other calculations, such as whether or not to generate the invoice in the first place, are not affected.:; check_freq - "1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq):; resetup - if set true, re-charges setup fees.; bill OPTIONS
+
:; invoice_time
 +
::Used in conjunction with the ''time'' option, this option specifies the date of for the generated invoices. Other calculations, such as whether or not to generate the invoice in the first place, are not affected.
 +
:; check_freq
 +
::"1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq)
 +
:; resetup
 +
::If set true, re-charges setup fees.
 +
:; debug
 +
::Debugging level. Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)
 +
; bill OPTIONS
 
:Generates invoices (see [[Freeside:1.9:Documentation:Developer/FS/cust bill|FS::cust_bill]]) for this customer. Usually used in conjunction with the collect method by calling '''bill_and_collect'''.
 
:Generates invoices (see [[Freeside:1.9:Documentation:Developer/FS/cust bill|FS::cust_bill]]) for this customer. Usually used in conjunction with the collect method by calling '''bill_and_collect'''.
  
Line 192: Line 300:
  
 
:Options are passed as name-value pairs. Currently available options are:
 
:Options are passed as name-value pairs. Currently available options are:
:; resetup - if set true, re-charges setup fees.:; time - bills the customer as if it were that time. Specified as a UNIX timestamp; see [[perlfunc#time|"time" in perlfunc]]). Also see [[Freeside:1.9:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:1.9:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions. For example&#58;<code>
+
:; resetup
 +
::If set true, re-charges setup fees.
 +
:; time
 +
::Bills the customer as if it were that time. Specified as a UNIX timestamp; see [[perlfunc#time|"time" in perlfunc]]). Also see [[Freeside:1.9:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:1.9:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions. For example:
 +
<code>
 
  use Date::Parse;
 
  use Date::Parse;
 
  ...
 
  ...
 
  $cust_main->bill( 'time' => str2time('April 20th, 2001') );
 
  $cust_main->bill( 'time' => str2time('April 20th, 2001') );
 
</code>
 
</code>
:; pkg_list - An array ref of specific packages (objects) to attempt billing, instead trying all of them.<code>
+
:; pkg_list
 +
::An array ref of specific packages (objects) to attempt billing, instead trying all of them.
 +
<code>
 
  $cust_main->bill( pkg_list => [$pkg1, $pkg2] );
 
  $cust_main->bill( pkg_list => [$pkg1, $pkg2] );
 
</code>
 
</code>
:; invoice_time - used in conjunction with the ''time'' option, this option specifies the date of for the generated invoices. Other calculations, such as whether or not to generate the invoice in the first place, are not affected.; collect OPTIONS
+
:; invoice_time
 +
::Used in conjunction with the ''time'' option, this option specifies the date of for the generated invoices. Other calculations, such as whether or not to generate the invoice in the first place, are not affected.
 +
; collect OPTIONS
 
:(Attempt to) collect money for this customer's outstanding invoices (see [[Freeside:1.9:Documentation:Developer/FS/cust bill|FS::cust_bill]]). Usually used after the bill method.
 
:(Attempt to) collect money for this customer's outstanding invoices (see [[Freeside:1.9:Documentation:Developer/FS/cust bill|FS::cust_bill]]). Usually used after the bill method.
  
Line 210: Line 326:
  
 
:Currently available options are:
 
:Currently available options are:
:; invoice_time - Use this time when deciding when to print invoices and late notices on those invoices. The default is now. It is specified as a UNIX timestamp; see [[perlfunc#time|"time" in perlfunc]]). Also see [[Freeside:1.9:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:1.9:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.:; retry - Retry card/echeck/LEC transactions even when not scheduled by invoice events.:; quiet - set true to surpress email card/ACH decline notices.:; check_freq - "1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq):; payby - allows for one time override of normal customer billing method:; due_cust_event [ HASHREF | OPTION => VALUE ... ]
+
:; invoice_time
::Inserts database records for and returns an ordered listref of new events due for this customer, as FS::cust_event objects (see [[Freeside:1.9:Documentation:Developer/FS/cust event|FS::cust_event]]). If no events are due, an empty listref is returned. If there is an error, returns a scalar error message.
+
::Use this time when deciding when to print invoices and late notices on those invoices. The default is now. It is specified as a UNIX timestamp; see [[perlfunc#time|"time" in perlfunc]]). Also see [[Freeside:1.9:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:1.9:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
 +
:; retry
 +
::Retry card/echeck/LEC transactions even when not scheduled by invoice events.
 +
:; quiet
 +
::set true to surpress email card/ACH decline notices.
 +
:; check_freq
 +
::"1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq)
 +
:; payby
 +
::allows for one time override of normal customer billing method
 +
:; debug
 +
::Debugging level. Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)
 +
; due_cust_event [ HASHREF | OPTION => VALUE ... ]
 +
:Inserts database records for and returns an ordered listref of new events due for this customer, as FS::cust_event objects (see [[Freeside:1.9:Documentation:Developer/FS/cust event|FS::cust_event]]). If no events are due, an empty listref is returned. If there is an error, returns a scalar error message.
  
::To actually run the events, call each event's test_condition method, and if still true, call the event's do_event method.
+
:To actually run the events, call each event's test_condition method, and if still true, call the event's do_event method.
  
::Options are passed as a hashref or as a list of name-value pairs. Available options are:
+
:Options are passed as a hashref or as a list of name-value pairs. Available options are:
::; check_freq - Search only for events of this check frequency (how often events of this type are checked); currently "1d" (daily, the default) and "1m" (monthly) are recognized.::; time - "Current time" for the events.::; debug - Debugging level. Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), or 3 (more information)::; eventtable - Only return events for the specified eventtable (by default, events of all eventtables are returned)::; objects - Explicitly pass the objects to be tested (typically used with eventtable).:; retry_realtime
+
:; check_freq
::Schedules realtime / batch credit card / electronic check / LEC billing events for for retry. Useful if card information has changed or manual retry is desired. The 'collect' method must be called to actually retry the transaction.
+
::Search only for events of this check frequency (how often events of this type are checked); currently "1d" (daily, the default) and "1m" (monthly) are recognized.
 +
:; time
 +
::"Current time" for the events.
 +
:; debug
 +
::Debugging level. Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)
 +
:; eventtable
 +
::Only return events for the specified eventtable (by default, events of all eventtables are returned)
 +
:; objects
 +
::Explicitly pass the objects to be tested (typically used with eventtable).
 +
:; testonly
 +
::Set to true to return the objects, but not actually insert them into the database.
 +
; retry_realtime
 +
:Schedules realtime / batch credit card / electronic check / LEC billing events for for retry. Useful if card information has changed or manual retry is desired. The 'collect' method must be called to actually retry the transaction.
  
::Implementation details: For either this customer, or for each of this customer's open invoices, changes the status of the first "done" (with statustext error) realtime processing event to "failed".
+
:Implementation details: For either this customer, or for each of this customer's open invoices, changes the status of the first "done" (with statustext error) realtime processing event to "failed".
:; realtime_bop METHOD AMOUNT [ OPTION => VALUE ... ]
+
; realtime_bop METHOD AMOUNT [ OPTION => VALUE ... ]
::Runs a realtime credit card, ACH (electronic check) or phone bill transaction via a Business::OnlinePayment realtime gateway. See http://420.am/business-onlinepayment for supported gateways.
+
:Runs a realtime credit card, ACH (electronic check) or phone bill transaction via a Business::OnlinePayment realtime gateway. See http://420.am/business-onlinepayment for supported gateways.
  
::Available methods are: ''CC'', ''ECHECK'' and ''LEC''
+
:Available methods are: ''CC'', ''ECHECK'' and ''LEC''
  
::Available options are: ''description'', ''invnum'', ''quiet''
+
:Available options are: ''description'', ''invnum'', ''quiet'', ''paynum_ref'', ''payunique''
  
::The additional options ''payname'', ''address1'', ''address2'', ''city'', ''state'', ''zip'', ''payinfo'' and ''paydate'' are also available. Any of these options, if set, will override the value from the customer record.
+
:The additional options ''payname'', ''address1'', ''address2'', ''city'', ''state'', ''zip'', ''payinfo'' and ''paydate'' are also available. Any of these options, if set, will override the value from the customer record.
  
::''description'' is a free-text field passed to the gateway. It defaults to "Internet services".
+
:''description'' is a free-text field passed to the gateway. It defaults to "Internet services".
  
::If an ''invnum'' is specified, this payment (if successful) is applied to the specified invoice. If you don't specify an ''invnum'' you might want to call the '''apply_payments''' method.
+
:If an ''invnum'' is specified, this payment (if successful) is applied to the specified invoice. If you don't specify an ''invnum'' you might want to call the '''apply_payments''' method.
  
::''quiet'' can be set true to surpress email decline notices.
+
:''quiet'' can be set true to surpress email decline notices.
  
::(moved from cust_bill) (probably should get realtime_{card,ach,lec} here too)
+
:''paynum_ref'' can be set to a scalar reference. It will be filled in with the resulting paynum, if any.
:; default_payment_gateway:; remove_cvv
 
::Removes the ''paycvv'' field from the database directly.
 
  
::If there is an error, returns the error, otherwise returns false.
+
:''payunique'' is a unique identifier for this payment.
:; realtime_refund_bop METHOD [ OPTION => VALUE ... ]
 
::Refunds a realtime credit card, ACH (electronic check) or phone bill transaction via a Business::OnlinePayment realtime gateway. See http://420.am/business-onlinepayment for supported gateways.
 
  
::Available methods are: ''CC'', ''ECHECK'' and ''LEC''
+
:(moved from cust_bill) (probably should get realtime_{card,ach,lec} here too)
 +
; fake_bop; default_payment_gateway; remove_cvv
 +
:Removes the ''paycvv'' field from the database directly.
  
::Available options are: ''amount'', ''reason'', ''paynum'', ''paydate''
+
:If there is an error, returns the error, otherwise returns false.
 +
; realtime_refund_bop METHOD [ OPTION => VALUE ... ]
 +
:Refunds a realtime credit card, ACH (electronic check) or phone bill transaction via a Business::OnlinePayment realtime gateway. See http://420.am/business-onlinepayment for supported gateways.
  
::Most gateways require a reference to an original payment transaction to refund, so you probably need to specify a ''paynum''.
+
:Available methods are: ''CC'', ''ECHECK'' and ''LEC''
  
::''amount'' defaults to the original amount of the payment if not specified.
+
:Available options are: ''amount'', ''reason'', ''paynum'', ''paydate''
  
::''reason'' specifies a reason for the refund.
+
:Most gateways require a reference to an original payment transaction to refund, so you probably need to specify a ''paynum''.
  
::''paydate'' specifies the expiration date for a credit card overriding the value from the customer record or the payment record. Specified as yyyy-mm-dd
+
:''amount'' defaults to the original amount of the payment if not specified.
  
::Implementation note: If ''amount'' is unspecified or equal to the amount of the orignal payment, first an attempt is made to "void" the transaction via the gateway (to cancel a not-yet settled transaction) and then if that fails, the normal attempt is made to "refund" ("credit") the transaction via the gateway is attempted.
+
:''reason'' specifies a reason for the refund.
  
::#The additional options ''payname'', ''address1'', ''address2'', ''city'', ''state'', #''zip'', ''payinfo'' and ''paydate'' are also available. Any of these options, #if set, will override the value from the customer record.
+
:''paydate'' specifies the expiration date for a credit card overriding the value from the customer record or the payment record. Specified as yyyy-mm-dd
  
::#If an ''invnum'' is specified, this payment (if successful) is applied to the #specified invoice. If you don't specify an ''invnum'' you might want to #call the '''apply_payments''' method.
+
:Implementation note: If ''amount'' is unspecified or equal to the amount of the orignal payment, first an attempt is made to "void" the transaction via the gateway (to cancel a not-yet settled transaction) and then if that fails, the normal attempt is made to "refund" ("credit") the transaction via the gateway is attempted.
:; batch_card OPTION => VALUE...
 
::Adds a payment for this invoice to the pending credit card batch (see [[Freeside:1.9:Documentation:Developer/FS/cust pay batch|FS::cust_pay_batch]]), or, if the '''realtime''' option is set to a true value, runs the payment using a realtime gateway.
 
:; total_owed
 
::Returns the total owed for this customer on all invoices (see [[Freeside:1.9:Documentation:Developer/FS/cust bill#owed|"owed" in FS/cust bill|FS::cust_bill#owed|"owed" in FS::cust_bill]]).
 
:; total_owed_date TIME
 
::Returns the total owed for this customer on all invoices with date earlier than TIME. TIME is specified as a UNIX timestamp; see [[perlfunc#time|"time" in perlfunc]]). Also see [[Freeside:1.9:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:1.9:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
 
:; apply_payments_and_credits
 
::Applies unapplied payments and credits.
 
  
::In most cases, this new method should be used in place of sequential apply_payments and apply_credits methods.
+
:#The additional options ''payname'', ''address1'', ''address2'', ''city'', ''state'', #''zip'', ''payinfo'' and ''paydate'' are also available. Any of these options, #if set, will override the value from the customer record.
  
::If there is an error, returns the error, otherwise returns false.
+
:#If an ''invnum'' is specified, this payment (if successful) is applied to the #specified invoice. If you don't specify an ''invnum'' you might want to #call the '''apply_payments''' method.
:; apply_credits OPTION => VALUE ...
+
; batch_card OPTION => VALUE...
::Applies (see [[Freeside:1.9:Documentation:Developer/FS/cust credit bill|FS::cust_credit_bill]]) unapplied credits (see [[Freeside:1.9:Documentation:Developer/FS/cust credit|FS::cust_credit]]) to outstanding invoice balances in chronological order (or reverse chronological order if the ''order'' option is set to '''newest''') and returns the value of any remaining unapplied credits available for refund (see [[Freeside:1.9:Documentation:Developer/FS/cust refund|FS::cust_refund]]).
+
:Adds a payment for this invoice to the pending credit card batch (see [[Freeside:1.9:Documentation:Developer/FS/cust pay batch|FS::cust_pay_batch]]), or, if the '''realtime''' option is set to a true value, runs the payment using a realtime gateway.
 +
; apply_payments_and_credits
 +
:Applies unapplied payments and credits.
  
::Dies if there is an error.
+
:In most cases, this new method should be used in place of sequential apply_payments and apply_credits methods.
:; apply_payments
+
 
::Applies (see [[Freeside:1.9:Documentation:Developer/FS/cust bill pay|FS::cust_bill_pay]]) unapplied payments (see [[Freeside:1.9:Documentation:Developer/FS/cust pay|FS::cust_pay]]) to outstanding invoice balances in chronological order.
+
:If there is an error, returns the error, otherwise returns false.
 +
; apply_credits OPTION => VALUE ...
 +
:Applies (see [[Freeside:1.9:Documentation:Developer/FS/cust credit bill|FS::cust_credit_bill]]) unapplied credits (see [[Freeside:1.9:Documentation:Developer/FS/cust credit|FS::cust_credit]]) to outstanding invoice balances in chronological order (or reverse chronological order if the ''order'' option is set to '''newest''') and returns the value of any remaining unapplied credits available for refund (see [[Freeside:1.9:Documentation:Developer/FS/cust refund|FS::cust_refund]]).
 +
 
 +
:Dies if there is an error.
 +
; apply_payments
 +
:Applies (see [[Freeside:1.9:Documentation:Developer/FS/cust bill pay|FS::cust_bill_pay]]) unapplied payments (see [[Freeside:1.9:Documentation:Developer/FS/cust pay|FS::cust_pay]]) to outstanding invoice balances in chronological order.
 
<code>
 
<code>
 
  #and returns the value of any remaining unapplied payments.
 
  #and returns the value of any remaining unapplied payments.
 
</code>
 
</code>
  
::Dies if there is an error.
+
:Dies if there is an error.
:; total_credited
+
; total_owed
::Returns the total outstanding credit (see [[Freeside:1.9:Documentation:Developer/FS/cust credit|FS::cust_credit]]) for this customer. See [[Freeside:1.9:Documentation:Developer/FS/cust credit#credited|"credited" in FS/cust credit|FS::cust_credit#credited|"credited" in FS::cust_credit]].
+
:Returns the total owed for this customer on all invoices (see [[Freeside:1.9:Documentation:Developer/FS/cust bill#owed|"owed" in FS/cust bill|FS::cust_bill#owed|"owed" in FS::cust_bill]]).
:; total_unapplied_payments
+
; total_owed_date TIME
::Returns the total unapplied payments (see [[Freeside:1.9:Documentation:Developer/FS/cust pay|FS::cust_pay]]) for this customer. See [[Freeside:1.9:Documentation:Developer/FS/cust pay#unapplied|"unapplied" in FS/cust pay|FS::cust_pay#unapplied|"unapplied" in FS::cust_pay]].
+
:Returns the total owed for this customer on all invoices with date earlier than TIME. TIME is specified as a UNIX timestamp; see [[perlfunc#time|"time" in perlfunc]]). Also see [[Freeside:1.9:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:1.9:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
:; total_unapplied_refunds
+
; total_paid
::Returns the total unrefunded refunds (see [[Freeside:1.9:Documentation:Developer/FS/cust refund|FS::cust_refund]]) for this customer. See [[Freeside:1.9:Documentation:Developer/FS/cust refund#unapplied|"unapplied" in FS/cust refund|FS::cust_refund#unapplied|"unapplied" in FS::cust_refund]].
+
:Returns the total amount of all payments.
:; balance
+
; total_unapplied_credits
::Returns the balance for this customer (total_owed plus total_unrefunded, minus total_credited minus total_unapplied_payments).
+
:Returns the total outstanding credit (see [[Freeside:1.9:Documentation:Developer/FS/cust credit|FS::cust_credit]]) for this customer. See [[Freeside:1.9:Documentation:Developer/FS/cust credit#credited|"credited" in FS/cust credit|FS::cust_credit#credited|"credited" in FS::cust_credit]].
:; balance_date TIME
+
; total_credited
::Returns the balance for this customer, only considering invoices with date earlier than TIME (total_owed_date minus total_credited minus total_unapplied_payments). TIME is specified as a UNIX timestamp; see [[perlfunc#time|"time" in perlfunc]]). Also see [[Freeside:1.9:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:1.9:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
+
:Old name for total_unapplied_credits. Don't use.
:; in_transit_payments
+
; total_unapplied_payments
::Returns the total of requests for payments for this customer pending in batches in transit to the bank. See [[Freeside:1.9:Documentation:Developer/FS/pay batch|FS::pay_batch]] and [[Freeside:1.9:Documentation:Developer/FS/cust pay batch|FS::cust_pay_batch]]
+
:Returns the total unapplied payments (see [[Freeside:1.9:Documentation:Developer/FS/cust pay|FS::cust_pay]]) for this customer. See [[Freeside:1.9:Documentation:Developer/FS/cust pay#unapplied|"unapplied" in FS/cust pay|FS::cust_pay#unapplied|"unapplied" in FS::cust_pay]].
:; paydate_monthyear
+
; total_unapplied_refunds
::Returns a two-element list consisting of the month and year of this customer's paydate (credit card expiration date for CARD customers)
+
:Returns the total unrefunded refunds (see [[Freeside:1.9:Documentation:Developer/FS/cust refund|FS::cust_refund]]) for this customer. See [[Freeside:1.9:Documentation:Developer/FS/cust refund#unapplied|"unapplied" in FS/cust refund|FS::cust_refund#unapplied|"unapplied" in FS::cust_refund]].
:; invoicing_list [ ARRAYREF ]
+
; balance
::If an arguement is given, sets these email addresses as invoice recipients (see [[Freeside:1.9:Documentation:Developer/FS/cust main invoice|FS::cust_main_invoice]]). Errors are not fatal and are not reported (except as warnings), so use check_invoicing_list first.
+
:Returns the balance for this customer (total_owed plus total_unrefunded, minus total_unapplied_credits minus total_unapplied_payments).
 +
; balance_date TIME
 +
:Returns the balance for this customer, only considering invoices with date earlier than TIME (total_owed_date minus total_credited minus total_unapplied_payments). TIME is specified as a UNIX timestamp; see [[perlfunc#time|"time" in perlfunc]]). Also see [[Freeside:1.9:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:1.9:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
 +
; in_transit_payments
 +
:Returns the total of requests for payments for this customer pending in batches in transit to the bank. See [[Freeside:1.9:Documentation:Developer/FS/pay batch|FS::pay_batch]] and [[Freeside:1.9:Documentation:Developer/FS/cust pay batch|FS::cust_pay_batch]]
 +
; paydate_monthyear
 +
:Returns a two-element list consisting of the month and year of this customer's paydate (credit card expiration date for CARD customers)
 +
; invoicing_list [ ARRAYREF ]
 +
:If an arguement is given, sets these email addresses as invoice recipients (see [[Freeside:1.9:Documentation:Developer/FS/cust main invoice|FS::cust_main_invoice]]). Errors are not fatal and are not reported (except as warnings), so use check_invoicing_list first.
 +
 
 +
:Returns a list of email addresses (with svcnum entries expanded).
 +
 
 +
:Note: You can clear the invoicing list by passing an empty ARRAYREF. You can check it without disturbing anything by passing nothing.
  
::Returns a list of email addresses (with svcnum entries expanded).
+
:This interface may change in the future.
 +
; check_invoicing_list ARRAYREF
 +
:Checks these arguements as valid input for the invoicing_list method. If there is an error, returns the error, otherwise returns false.
 +
; set_default_invoicing_list
 +
:Sets the invoicing list to all accounts associated with this customer, overwriting any previous invoicing list.
 +
; all_emails
 +
:Returns the email addresses of all accounts provisioned for this customer.
 +
; invoicing_list_addpost
 +
:Adds postal invoicing to this customer. If this customer is already configured to receive postal invoices, does nothing.
 +
; invoicing_list_emailonly
 +
:Returns the list of email invoice recipients (invoicing_list without non-email destinations such as POST and FAX).
 +
; invoicing_list_emailonly_scalar
 +
:Returns the list of email invoice recipients (invoicing_list without non-email destinations such as POST and FAX) as a comma-separated scalar.
 +
; referral_cust_main [ DEPTH [ EXCLUDE_HASHREF ] ]
 +
:Returns an array of customers referred by this customer (referral_custnum set to this custnum). If DEPTH is given, recurses up to the given depth, returning customers referred by customers referred by this customer and so on, inclusive. The default behavior is DEPTH 1 (no recursion).
 +
; referral_cust_main_ncancelled
 +
:Same as referral_cust_main, except only returns customers with uncancelled packages.
 +
; referral_cust_pkg [ DEPTH ]
 +
:Like referral_cust_main, except returns a flat list of all unsuspended (and uncancelled) packages for each customer. The number of items in this list may be useful for comission calculations (perhaps after a <tt>grep { my $pkgpart = $_-</tt>pkgpart; grep { $_ == $pkgpart } @commission_worthy_pkgparts> } $cust_main-> ).
 +
; referring_cust_main
 +
:Returns the single cust_main record for the customer who referred this customer (referral_custnum), or false.
 +
; credit AMOUNT, REASON [ , OPTION => VALUE ... ]
 +
:Applies a credit to this customer. If there is an error, returns the error, otherwise returns false.
  
::Note: You can clear the invoicing list by passing an empty ARRAYREF. You can check it without disturbing anything by passing nothing.
+
:REASON can be a text string, an FS::reason object, or a scalar reference to a reasonnum. If a text string, it will be automatically inserted as a new reason, and a 'reason_type' option must be passed to indicate the FS::reason_type for the new reason.
  
::This interface may change in the future.
+
:An ''addlinfo'' option may be passed to set the credit's ''addlinfo'' field.
:; check_invoicing_list ARRAYREF
+
 
::Checks these arguements as valid input for the invoicing_list method. If there is an error, returns the error, otherwise returns false.
+
:Any other options are passed to FS::cust_credit::insert.
:; set_default_invoicing_list
+
; charge AMOUNT [ PKG [ COMMENT [ TAXCLASS ] ] ]
::Sets the invoicing list to all accounts associated with this customer, overwriting any previous invoicing list.
+
:Creates a one-time charge for this customer. If there is an error, returns the error, otherwise returns false.
:; all_emails
+
; cust_bill
::Returns the email addresses of all accounts provisioned for this customer.
+
:Returns all the invoices (see [[Freeside:1.9:Documentation:Developer/FS/cust bill|FS::cust_bill]]) for this customer.
:; invoicing_list_addpost
+
; open_cust_bill
::Adds postal invoicing to this customer. If this customer is already configured to receive postal invoices, does nothing.
+
:Returns all the open (owed > 0) invoices (see [[Freeside:1.9:Documentation:Developer/FS/cust bill|FS::cust_bill]]) for this customer.
:; invoicing_list_emailonly
+
; cust_credit
::Returns the list of email invoice recipients (invoicing_list without non-email destinations such as POST and FAX).
+
:Returns all the credits (see [[Freeside:1.9:Documentation:Developer/FS/cust credit|FS::cust_credit]]) for this customer.
:; invoicing_list_emailonly_scalar
+
; cust_pay
::Returns the list of email invoice recipients (invoicing_list without non-email destinations such as POST and FAX) as a comma-separated scalar.
+
:Returns all the payments (see [[Freeside:1.9:Documentation:Developer/FS/cust pay|FS::cust_pay]]) for this customer.
:; referral_cust_main [ DEPTH [ EXCLUDE_HASHREF ] ]
+
; cust_pay_void
::Returns an array of customers referred by this customer (referral_custnum set to this custnum). If DEPTH is given, recurses up to the given depth, returning customers referred by customers referred by this customer and so on, inclusive. The default behavior is DEPTH 1 (no recursion).
+
:Returns all voided payments (see [[Freeside:1.9:Documentation:Developer/FS/cust pay void|FS::cust_pay_void]]) for this customer.
:; referral_cust_main_ncancelled
+
; cust_pay_batch
::Same as referral_cust_main, except only returns customers with uncancelled packages.
+
:Returns all batched payments (see [[Freeside:1.9:Documentation:Developer/FS/cust pay void|FS::cust_pay_void]]) for this customer.
:; referral_cust_pkg [ DEPTH ]
+
; cust_refund
::Like referral_cust_main, except returns a flat list of all unsuspended (and uncancelled) packages for each customer. The number of items in this list may be useful for comission calculations (perhaps after a <tt>grep { my $pkgpart = $_-</tt>pkgpart; grep { $_ == $pkgpart } @commission_worthy_pkgparts> } $cust_main-> ).
+
:Returns all the refunds (see [[Freeside:1.9:Documentation:Developer/FS/cust refund|FS::cust_refund]]) for this customer.
:; referring_cust_main
+
; display_custnum
::Returns the single cust_main record for the customer who referred this customer (referral_custnum), or false.
+
:Returns the displayed customer number for this customer: agent_custid if cust_main-default_agent_custid is set and it has a value, custnum otherwise.
:; credit AMOUNT, REASON
+
; name
::Applies a credit to this customer. If there is an error, returns the error, otherwise returns false.
+
:Returns a name string for this customer, either "Company (Last, First)" or "Last, First".
:; charge AMOUNT [ PKG [ COMMENT [ TAXCLASS ] ] ]
+
; ship_name
::Creates a one-time charge for this customer. If there is an error, returns the error, otherwise returns false.
+
:Returns a name string for this (service/shipping) contact, either "Company (Last, First)" or "Last, First".
:; cust_bill
+
; name_short
::Returns all the invoices (see [[Freeside:1.9:Documentation:Developer/FS/cust bill|FS::cust_bill]]) for this customer.
+
:Returns a name string for this customer, either "Company" or "First Last".
:; open_cust_bill
+
; ship_name_short
::Returns all the open (owed > 0) invoices (see [[Freeside:1.9:Documentation:Developer/FS/cust bill|FS::cust_bill]]) for this customer.
+
:Returns a name string for this (service/shipping) contact, either "Company" or "First Last".
:; cust_credit
+
; contact
::Returns all the credits (see [[Freeside:1.9:Documentation:Developer/FS/cust credit|FS::cust_credit]]) for this customer.
+
:Returns this customer's full (billing) contact name only, "Last, First"
:; cust_pay
+
; ship_contact
::Returns all the payments (see [[Freeside:1.9:Documentation:Developer/FS/cust pay|FS::cust_pay]]) for this customer.
+
:Returns this customer's full (shipping) contact name only, "Last, First"
:; cust_pay_void
+
; contact_firstlast
::Returns all voided payments (see [[Freeside:1.9:Documentation:Developer/FS/cust pay void|FS::cust_pay_void]]) for this customer.
+
:Returns this customers full (billing) contact name only, "First Last".
:; cust_pay_batch
+
; ship_contact_firstlast
::Returns all batched payments (see [[Freeside:1.9:Documentation:Developer/FS/cust pay void|FS::cust_pay_void]]) for this customer.
+
:Returns this customer's full (shipping) contact name only, "First Last".
:; cust_refund
+
; country_full
::Returns all the refunds (see [[Freeside:1.9:Documentation:Developer/FS/cust refund|FS::cust_refund]]) for this customer.
+
:Returns this customer's full country name
:; name
+
; geocode DATA_VENDOR
::Returns a name string for this customer, either "Company (Last, First)" or "Last, First".
+
:Returns a value for the customer location as encoded by DATA_VENDOR. Currently this only makes sense for "CCH" as DATA_VENDOR.
:; ship_name
+
; cust_status; status
::Returns a name string for this (service/shipping) contact, either "Company (Last, First)" or "Last, First".
+
:Returns a status string for this customer, currently:
:; contact
+
:; prospect - No packages have ever been ordered:; active - One or more recurring packages is active:; inactive - No active recurring packages, but otherwise unsuspended/uncancelled (the inactive status is new - previously inactive customers were mis-identified as cancelled):; suspended - All non-cancelled recurring packages are suspended:; cancelled - All recurring packages are cancelled; ucfirst_cust_status; ucfirst_status
::Returns this customer's full (billing) contact name only, "Last, First"
+
:Returns the status with the first character capitalized.
:; ship_contact
+
; statuscolor
::Returns this customer's full (shipping) contact name only, "Last, First"
+
:Returns a hex triplet color string for this customer's status.
:; country_full
+
; tickets
::Returns this customer's full country name
+
:Returns an array of hashes representing the customer's RT tickets.
:; cust_status:; status
 
::Returns a status string for this customer, currently:
 
::; prospect - No packages have ever been ordered::; active - One or more recurring packages is active::; inactive - No active recurring packages, but otherwise unsuspended/uncancelled (the inactive status is new - previously inactive customers were mis-identified as cancelled)::; suspended - All non-cancelled recurring packages are suspended::; cancelled - All recurring packages are cancelled:; ucfirst_cust_status:; ucfirst_status
 
::Returns the status with the first character capitalized.
 
:; statuscolor
 
::Returns a hex triplet color string for this customer's status.
 
:; tickets
 
::Returns an array of hashes representing the customer's RT tickets.
 
  
 
==CLASS METHODS==
 
==CLASS METHODS==
Line 371: Line 537:
 
:Returns an SQL expression identifying prospective cust_main records (customers with no packages ever ordered)
 
:Returns an SQL expression identifying prospective cust_main records (customers with no packages ever ordered)
 
; active_sql
 
; active_sql
:Returns an SQL expression identifying active cust_main records (customers with no active recurring packages, but otherwise unsuspended/uncancelled).
+
:Returns an SQL expression identifying active cust_main records (customers with active recurring packages).
 
; inactive_sql
 
; inactive_sql
:Returns an SQL expression identifying inactive cust_main records (customers with active recurring packages).
+
:Returns an SQL expression identifying inactive cust_main records (customers with no active recurring packages, but otherwise unsuspended/uncancelled).
 
; susp_sql =item suspended_sql
 
; susp_sql =item suspended_sql
 
:Returns an SQL expression identifying suspended cust_main records.
 
:Returns an SQL expression identifying suspended cust_main records.
Line 382: Line 548:
 
; balance_sql
 
; balance_sql
 
:Returns an SQL fragment to retreive the balance.
 
:Returns an SQL fragment to retreive the balance.
; balance_date_sql TIME
+
; balance_date_sql START_TIME [ END_TIME [ OPTION => VALUE ... ] ]
:Returns an SQL fragment to retreive the balance for this customer, only considering invoices with date earlier than TIME. (total_owed_date minus total_credited minus total_unapplied_payments). TIME is specified as an SQL fragment or a numeric UNIX timestamp; see [[perlfunc#time|"time" in perlfunc]]). Also see [[Freeside:1.9:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:1.9:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
+
:Returns an SQL fragment to retreive the balance for this customer, only considering invoices with date earlier than START_TIME, and optionally not later than END_TIME (total_owed_date minus total_unapplied_credits minus total_unapplied_payments).
 +
 
 +
:Times are specified as SQL fragments or numeric UNIX timestamps; see [[perlfunc#time|"time" in perlfunc]]). Also see [[Freeside:1.9:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:1.9:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions. The empty string can be passed to disable that time constraint completely.
 +
 
 +
:Available options are:
 +
:; unapplied_date
 +
::set to true to disregard unapplied credits, payments and refunds outside the specified time period - by default the time period restriction only applies to invoices (useful for reporting, probably a bad idea for event triggering)
 +
:; total
 +
::(unused. obsolete?) set to true to remove all customer comparison clauses, for totals
 +
:; where
 +
::(unused. obsolete?) WHERE clause hashref (elements "AND"ed together) (typically used with the total option)
 +
:; join
 +
::(unused. obsolete?) JOIN clause (typically used with the total option)
 +
; _money_table_where TABLE START_TIME [ END_TIME [ OPTION => VALUE ... ] ]
 +
:Helper method for balance_date_sql; name (and usage) subject to change (suggestions welcome).
 +
 
 +
:Returns a WHERE clause for the specified monetary TABLE (cust_bill, cust_refund, cust_credit or cust_pay).
 +
 
 +
:If TABLE is "cust_bill" or the unapplied_date option is true, only considers records with date earlier than START_TIME, and optionally not later than END_TIME .
 +
; search_sql HASHREF
 +
:(Class method)
 +
 
 +
:Returns a qsearch hash expression to search for parameters specified in HREF. Valid parameters are
 +
:; agentnum:; status:; cancelled_pkgs
 +
::bool
 +
:; signupdate
 +
::listref of start date, end date
 +
:; payby
 +
::listref
 +
:; current_balance
 +
::listref (list returned by FS::UI::Web::parse_lt_gt($cgi, 'current_balance'))
 +
:; cust_fields:; flattened_pkgs
 +
::bool
 +
; email_search_sql HASHREF
 +
:(Class method)
 +
 
 +
:Emails a notice to the specified customers.
 +
 
 +
:Valid parameters are those of the [[Freeside:1.9:Documentation:Developer/search sql|search_sql]] method, plus the following:
 +
:; from
 +
::From: address
 +
:; subject
 +
::Email Subject:
 +
:; html_body
 +
::HTML body
 +
:; text_body
 +
::Text body
 +
:; job
 +
::Optional job queue job for status updates.
 +
 
 +
:Returns an error message, or false for success.
 +
 
 +
:If an error occurs during any email, stops the enture send and returns that error. Presumably if you're getting SMTP errors aborting is better than retrying everything.
 
; fuzzy_search FUZZY_HASHREF [ HASHREF, SELECT, EXTRA_SQL, CACHE_OBJ ]
 
; fuzzy_search FUZZY_HASHREF [ HASHREF, SELECT, EXTRA_SQL, CACHE_OBJ ]
 
:Performs a fuzzy (approximate) search and returns the matching FS::cust_main records. Currently, ''first'', ''last'' and/or ''company'' may be specified (the appropriate ship_ field is also searched).
 
:Performs a fuzzy (approximate) search and returns the matching FS::cust_main records. Currently, ''first'', ''last'' and/or ''company'' may be specified (the appropriate ship_ field is also searched).
Line 398: Line 616:
  
 
:Returns a (possibly empty) array of FS::cust_main objects.
 
:Returns a (possibly empty) array of FS::cust_main objects.
; check_and_rebuild_fuzzyfiles; rebuild_fuzzyfiles; all_X; append_fuzzyfiles LASTNAME COMPANY; batch_import; batch_charge; notify CUSTOMER_OBJECT TEMPLATE_NAME OPTIONS
+
; email_search
 +
:Accepts the following options: ''email'', the email address to search for. The email address will be searched for as an email invoice destination and as an svc_acct account.
 +
 
 +
:#Any additional options are treated as an additional qualifier on the search #(i.e. ''agentnum'').
 +
 
 +
:Returns a (possibly empty) array of FS::cust_main objects (but usually just none or one).
 +
; check_and_rebuild_fuzzyfiles; rebuild_fuzzyfiles; all_X; append_fuzzyfiles LASTNAME COMPANY; batch_charge; notify CUSTOMER_OBJECT TEMPLATE_NAME OPTIONS
 
:Sends a templated email notification to the customer (see [[Freeside:1.9:Documentation:Developer/Text/Template|Text::Template]]).
 
:Sends a templated email notification to the customer (see [[Freeside:1.9:Documentation:Developer/Text/Template|Text::Template]]).
  
Line 423: Line 647:
 
:The following variables are available in the template instead of or in addition to the fields of the customer record.
 
:The following variables are available in the template instead of or in addition to the fields of the customer record.
  
:''$payby'' - a description of the method of payment for the customer # would be nice to use FS::payby::shortname ''$payinfo'' - the masked account information used to collect for this customer ''$expdate'' - the expiration of the customer payment method in seconds from epoch ''$returnaddress'' - the return address defaults to invoice_latexreturnaddress
+
:''$payby'' - a description of the method of payment for the customer # would be nice to use FS::payby::shortname ''$payinfo'' - the masked account information used to collect for this customer ''$expdate'' - the expiration of the customer payment method in seconds from epoch ''$returnaddress'' - the return address defaults to invoice_latexreturnaddress or company_address
 
; print_ps TEMPLATE
 
; print_ps TEMPLATE
 
:Returns an postscript letter filled in from TEMPLATE, as a scalar.
 
:Returns an postscript letter filled in from TEMPLATE, as a scalar.
Line 452: Line 676:
 
==SEE ALSO==
 
==SEE ALSO==
 
[[Freeside:1.9:Documentation:Developer/FS/Record|FS::Record]], [[Freeside:1.9:Documentation:Developer/FS/cust pkg|FS::cust_pkg]], [[Freeside:1.9:Documentation:Developer/FS/cust bill|FS::cust_bill]], [[Freeside:1.9:Documentation:Developer/FS/cust credit|FS::cust_credit]] [[Freeside:1.9:Documentation:Developer/FS/agent|FS::agent]], [[Freeside:1.9:Documentation:Developer/FS/part referral|FS::part_referral]], [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]], [[Freeside:1.9:Documentation:Developer/FS/cust main invoice|FS::cust_main_invoice]], [[Freeside:1.9:Documentation:Developer/FS/UID|FS::UID]], schema.html from the base documentation.
 
[[Freeside:1.9:Documentation:Developer/FS/Record|FS::Record]], [[Freeside:1.9:Documentation:Developer/FS/cust pkg|FS::cust_pkg]], [[Freeside:1.9:Documentation:Developer/FS/cust bill|FS::cust_bill]], [[Freeside:1.9:Documentation:Developer/FS/cust credit|FS::cust_credit]] [[Freeside:1.9:Documentation:Developer/FS/agent|FS::agent]], [[Freeside:1.9:Documentation:Developer/FS/part referral|FS::part_referral]], [[Freeside:1.9:Documentation:Developer/FS/cust main county|FS::cust_main_county]], [[Freeside:1.9:Documentation:Developer/FS/cust main invoice|FS::cust_main_invoice]], [[Freeside:1.9:Documentation:Developer/FS/UID|FS::UID]], schema.html from the base documentation.
 
==POD ERRORS==
 
Hey! '''The above document had some coding errors, which are explained below:'''
 
 
; Around line 4703&#58;
 
:You forgot a '=back' before '=head1'
 

Latest revision as of 18:14, 6 February 2009

NAME

FS::cust_main - Object methods for cust_main records

SYNOPSIS

 use FS::cust_main;

 $record = new FS::cust_main \%hash;
 $record = new FS::cust_main { 'column' => 'value' };

 $error = $record->insert;

 $error = $new_record->replace($old_record);

 $error = $record->delete;

 $error = $record->check;

 @cust_pkg = $record->all_pkgs;

 @cust_pkg = $record->ncancelled_pkgs;

 @cust_pkg = $record->suspended_pkgs;

 $error = $record->bill;
 $error = $record->bill %options;
 $error = $record->bill 'time' => $time;

 $error = $record->collect;
 $error = $record->collect %options;
 $error = $record->collect 'invoice_time'   => $time,
                         ;

DESCRIPTION

An FS::cust_main object represents a customer. FS::cust_main inherits from FS::Record. The following fields are currently supported:

custnum
Primary key (assigned automatically for new customers)
agentnum
Agent (see FS::agent)
refnum
Advertising source (see FS::part_referral)
first
First name
last
Last name
ss
Cocial security number (optional)
company
(optional)
address1; address2
(optional)
city; county
(optional, see FS::cust_main_county)
state
(see FS::cust_main_county)
zip; country
(see FS::cust_main_county)
daytime
phone (optional)
night
phone (optional)
fax
phone (optional)
ship_first
Shipping first name
ship_last
Shipping last name
ship_company
(optional)
ship_address1; ship_address2
(optional)
ship_city; ship_county
(optional, see FS::cust_main_county)
ship_state
(see FS::cust_main_county)
ship_zip; ship_country
(see FS::cust_main_county)
ship_daytime
phone (optional)
ship_night
phone (optional)
ship_fax
phone (optional)
payby
Payment Type (See FS::payinfo_Mixin for valid payby values)
payinfo
Payment Information (See FS::payinfo_Mixin for data format)
paymask
Masked payinfo (See FS::payinfo_Mixin for how this works)
paycvv
Card Verification Value, "CVV2" (also known as CVC2 or CID), the 3 or 4 digit number on the back (or front, for American Express) of the credit card
paydate
Expiration date, mm/yyyy, m/yyyy, mm/yy or m/yy
paystart_month
Start date month (maestro/solo cards only)
paystart_year
Start date year (maestro/solo cards only)
payissue
Issue number (maestro/solo cards only)
payname
Name on card or billing name
payip
IP address from which payment information was received
tax
Tax exempt, empty or `Y'
otaker
Order taker (assigned automatically, see FS::UID)
comments
Comments (optional)
referral_custnum
Referring customer number
spool_cdr
Enable individual CDR spooling, empty or `Y'
dundate
A suggestion to events (see FS::part_bill_event") to delay until this unix timestamp
squelch_cdr
Discourage individual CDR printing, empty or `Y'

METHODS

new HASHREF
Creates a new customer. To add the customer to the database, see "insert".
Note that this stores the hash reference, not a distinct copy of the hash it points to. You can ask the object for a copy with the hash method.
insert [ CUST_PKG_HASHREF [ , INVOICING_LIST_ARYREF ] [ , OPTION => VALUE ... ] ]
Adds this customer to the database. If there is an error, returns the error, otherwise returns false.
CUST_PKG_HASHREF: If you pass a Tie::RefHash data structure to the insert method containing FS::cust_pkg and FS::svc_tablename objects, all records are inserted atomicly, or the transaction is rolled back. Passing an empty hash reference is equivalent to not supplying this parameter. There should be a better explanation of this, but until then, here's an example:

 use Tie::RefHash;
 tie %hash, 'Tie::RefHash'; #this part is important
 %hash = (
   $cust_pkg => [ $svc_acct ],
   ...
 );
 $cust_main->insert( \%hash );

INVOICING_LIST_ARYREF: If you pass an arrarref to the insert method, it will be set as the invoicing list (see "invoicing_list"). Errors return as expected and rollback the entire transaction; it is not necessary to call check_invoicing_list first. The invoicing_list is set after the records in the CUST_PKG_HASHREF above are inserted, so it is now possible to set an invoicing_list destination to the newly-created svc_acct. Here's an example:

 $cust_main->insert( {}, [ $email, 'POST' ] );

Currently available options are: depend_jobnum and noexport.
If depend_jobnum is set, all provisioning jobs will have a dependancy on the supplied jobnum (they will not run until the specific job completes). This can be used to defer provisioning until some action completes (such as running the customer's credit card successfully).
The noexport option is deprecated. If noexport is set true, no provisioning jobs (exports) are scheduled. (You can schedule them later with the reexport method.)
order_pkg HASHREF | OPTION => VALUE ...
Orders a single package.
Options may be passed as a list of key/value pairs or as a hash reference. Options are:
cust_pkg
FS::cust_pkg object
cust_location
Optional FS::cust_location object
svcs
Optional arryaref of FS::svc_* service objects.
depend_jobnum
If this option is set to a job queue jobnum (see FS::queue), all provisioning jobs will have a dependancy on the supplied job (they will not run until the specific job completes). This can be used to defer provisioning until some action completes (such as running the customer's credit card successfully).
order_pkgs HASHREF, [ SECONDSREF, [ , OPTION => VALUE ... ] ]
Like the insert method on an existing record, this method orders multiple packages and included services atomicaly. Pass a Tie::RefHash data structure to this method containing FS::cust_pkg and FS::svc_tablename objects. There should be a better explanation of this, but until then, here's an example:

 use Tie::RefHash;
 tie %hash, 'Tie::RefHash'; #this part is important
 %hash = (
   $cust_pkg => [ $svc_acct ],
   ...
 );
 $cust_main->order_pkgs( \%hash, \'0', 'noexport'=>1 );

Services can be new, in which case they are inserted, or existing unaudited services, in which case they are linked to the newly-created package.
Currently available options are: depend_jobnum and noexport.
If depend_jobnum is set, all provisioning jobs will have a dependancy on the supplied jobnum (they will not run until the specific job completes). This can be used to defer provisioning until some action completes (such as running the customer's credit card successfully).
The noexport option is deprecated. If noexport is set true, no provisioning jobs (exports) are scheduled. (You can schedule them later with the reexport method for each cust_pkg object. Using the reexport method on the cust_main object is not recommended, as existing services will also be reexported.)
recharge_prepay IDENTIFIER | PREPAY_CREDIT_OBJ [ , AMOUNTREF, SECONDSREF, UPBYTEREF, DOWNBYTEREF ]
Recharges this (existing) customer with the specified prepaid card (see FS::prepay_credit), specified either by identifier or as an FS::prepay_credit object. If there is an error, returns the error, otherwise returns false.
Optionally, four scalar references can be passed as well. They will have their values filled in with the amount, number of seconds, and number of upload and download bytes applied by this prepaid card.
get_prepay IDENTIFIER | PREPAY_CREDIT_OBJ , AMOUNTREF, SECONDSREF
Looks up and deletes a prepaid card (see FS::prepay_credit), specified either by identifier or as an FS::prepay_credit object.
References to amount and seconds scalars should be passed as arguments and will be incremented by the values of the prepaid card.
If the prepaid card specifies an agentnum (see FS::agent), it is used to check or set this customer's agentnum.
If there is an error, returns the error, otherwise returns false.
increment_upbytes SECONDS
Updates this customer's single or primary account (see FS::svc_acct) by the specified number of upbytes. If there is an error, returns the error, otherwise returns false.
increment_downbytes SECONDS
Updates this customer's single or primary account (see FS::svc_acct) by the specified number of downbytes. If there is an error, returns the error, otherwise returns false.
increment_totalbytes SECONDS
Updates this customer's single or primary account (see FS::svc_acct) by the specified number of totalbytes. If there is an error, returns the error, otherwise returns false.
increment_seconds SECONDS
Updates this customer's single or primary account (see FS::svc_acct) by the specified number of seconds. If there is an error, returns the error, otherwise returns false.
_increment_column AMOUNT
Updates this customer's single or primary account (see FS::svc_acct) by the specified number of seconds or bytes. If there is an error, returns the error, otherwise returns false.
insert_cust_pay_prepay AMOUNT [ PAYINFO ]
Inserts a prepayment in the specified amount for this customer. An optional second argument can specify the prepayment identifier for tracking purposes. If there is an error, returns the error, otherwise returns false.
insert_cust_pay_cash AMOUNT [ PAYINFO ]
Inserts a cash payment in the specified amount for this customer. An optional second argument can specify the payment identifier for tracking purposes. If there is an error, returns the error, otherwise returns false.
insert_cust_pay_west AMOUNT [ PAYINFO ]
Inserts a Western Union payment in the specified amount for this customer. An optional second argument can specify the prepayment identifier for tracking purposes. If there is an error, returns the error, otherwise returns false.
reexport
This method is deprecated. See the depend_jobnum option to the insert and order_pkgs methods for a better way to defer provisioning.
Re-schedules all exports by calling the reexport method of all associated packages (see FS::cust_pkg). If there is an error, returns the error; otherwise returns false.
delete NEW_CUSTNUM
This deletes the customer. If there is an error, returns the error, otherwise returns false.
This will completely remove all traces of the customer record. This is not what you want when a customer cancels service; for that, cancel all of the customer's packages (see "cancel").
If the customer has any uncancelled packages, you need to pass a new (valid) customer number for those packages to be transferred to. Cancelled packages will be deleted. Did I mention that this is NOT what you want when a customer cancels service and that you really should be looking see "cancel" in FS/cust pkg|FS::cust_pkg#cancel|"cancel" in FS::cust_pkg?
You can't delete a customer with invoices (see FS::cust_bill), or credits (see FS::cust_credit), payments (see FS::cust_pay) or refunds (see FS::cust_refund).
replace [ OLD_RECORD ] [ INVOICING_LIST_ARYREF ]
Replaces the OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
INVOICING_LIST_ARYREF: If you pass an arrarref to the insert method, it will be set as the invoicing list (see "invoicing_list"). Errors return as expected and rollback the entire transaction; it is not necessary to call check_invoicing_list first. Here's an example:

 $new_cust_main->replace( $old_cust_main, [ $email, 'POST' ] );

queue_fuzzyfiles_update
Used by insert & replace to update the fuzzy search cache
check
Checks all fields to make sure this is a valid customer record. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
addr_fields
Returns a list of fields which have ship_ duplicates.
has_ship_address
Returns true if this customer record has a separate shipping address.
all_pkgs
Returns all packages (see FS::cust_pkg) for this customer.
cust_pkg
Synonym for all_pkgs.
cust_location
Returns all locations (see FS::cust_location) for this customer.
ncancelled_pkgs
Returns all non-cancelled packages (see FS::cust_pkg) for this customer.
suspended_pkgs
Returns all suspended packages (see FS::cust_pkg) for this customer.
unflagged_suspended_pkgs
Returns all unflagged suspended packages (see FS::cust_pkg) for this customer (thouse packages without the `manual_flag' set).
unsuspended_pkgs
Returns all unsuspended (and uncancelled) packages (see FS::cust_pkg) for this customer.
num_cancelled_pkgs
Returns the number of cancelled packages (see FS::cust_pkg) for this customer.
unsuspend
Unsuspends all unflagged suspended packages (see "unflagged_suspended_pkgs" and FS::cust_pkg) for this customer. Always returns a list: an empty list on success or a list of errors.
suspend
Suspends all unsuspended packages (see FS::cust_pkg) for this customer.
Returns a list: an empty list on success or a list of errors.
suspend_if_pkgpart HASHREF | PKGPART [ , PKGPART ... ]
Suspends all unsuspended packages (see FS::cust_pkg) matching the listed PKGPARTs (see FS::part_pkg). Preferred usage is to pass a hashref instead of a list of pkgparts; the hashref has the following keys:
pkgparts - listref of pkgparts
; (other options are passed to the suspend method)
Returns a list: an empty list on success or a list of errors.
suspend_unless_pkgpart HASHREF | PKGPART [ , PKGPART ... ]
Suspends all unsuspended packages (see FS::cust_pkg) unless they match the given PKGPARTs (see FS::part_pkg). Preferred usage is to pass a hashref instead of a list of pkgparts; the hashref has the following keys:
pkgparts - listref of pkgparts
; (other options are passed to the suspend method)
Returns a list: an empty list on success or a list of errors.
cancel [ OPTION => VALUE ... ]
Cancels all uncancelled packages (see FS::cust_pkg) for this customer.
Available options are:
quiet - can be set true to supress email cancellation notices.
; reason - can be set to a cancellation reason (see FS:reason), either a reasonnum of an existing reason, or passing a hashref will create a new reason. The hashref should have the following keys: typenum - Reason type (see FS::reason_type, reason - Text of the new reason.:; ban - can be set true to ban this customer's credit card or ACH information, if present.
Always returns a list: an empty list on success or a list of errors.
notes
Returns all notes (see FS::cust_main_note) for this customer.
agent
Returns the agent (see FS::agent) for this customer.
bill_and_collect
Cancels and suspends any packages due, generates bills, applies payments and cred
Warns on errors (Does not currently: If there is an error, returns the error, otherwise returns false.)
Options are passed as name-value pairs. Currently available options are:
time
Bills the customer as if it were that time. Specified as a UNIX timestamp; see "time" in perlfunc). Also see Time::Local and Date::Parse for conversion functions. For example:

use Date::Parse;
...
$cust_main->bill( 'time' => str2time('April 20th, 2001') );

invoice_time
Used in conjunction with the time option, this option specifies the date of for the generated invoices. Other calculations, such as whether or not to generate the invoice in the first place, are not affected.
check_freq
"1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq)
resetup
If set true, re-charges setup fees.
debug
Debugging level. Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)
bill OPTIONS
Generates invoices (see FS::cust_bill) for this customer. Usually used in conjunction with the collect method by calling bill_and_collect.
If there is an error, returns the error, otherwise returns false.
Options are passed as name-value pairs. Currently available options are:
resetup
If set true, re-charges setup fees.
time
Bills the customer as if it were that time. Specified as a UNIX timestamp; see "time" in perlfunc). Also see Time::Local and Date::Parse for conversion functions. For example:

use Date::Parse;
...
$cust_main->bill( 'time' => str2time('April 20th, 2001') );

pkg_list
An array ref of specific packages (objects) to attempt billing, instead trying all of them.

$cust_main->bill( pkg_list => [$pkg1, $pkg2] );

invoice_time
Used in conjunction with the time option, this option specifies the date of for the generated invoices. Other calculations, such as whether or not to generate the invoice in the first place, are not affected.
collect OPTIONS
(Attempt to) collect money for this customer's outstanding invoices (see FS::cust_bill). Usually used after the bill method.
Actions are now triggered by billing events; see FS::part_event and the billing events web interface. Old-style invoice events (see FS::part_bill_event) have been deprecated.
If there is an error, returns the error, otherwise returns false.
Options are passed as name-value pairs.
Currently available options are:
invoice_time
Use this time when deciding when to print invoices and late notices on those invoices. The default is now. It is specified as a UNIX timestamp; see "time" in perlfunc). Also see Time::Local and Date::Parse for conversion functions.
retry
Retry card/echeck/LEC transactions even when not scheduled by invoice events.
quiet
set true to surpress email card/ACH decline notices.
check_freq
"1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq)
payby
allows for one time override of normal customer billing method
debug
Debugging level. Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)
due_cust_event [ HASHREF | OPTION => VALUE ... ]
Inserts database records for and returns an ordered listref of new events due for this customer, as FS::cust_event objects (see FS::cust_event). If no events are due, an empty listref is returned. If there is an error, returns a scalar error message.
To actually run the events, call each event's test_condition method, and if still true, call the event's do_event method.
Options are passed as a hashref or as a list of name-value pairs. Available options are:
check_freq
Search only for events of this check frequency (how often events of this type are checked); currently "1d" (daily, the default) and "1m" (monthly) are recognized.
time
"Current time" for the events.
debug
Debugging level. Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)
eventtable
Only return events for the specified eventtable (by default, events of all eventtables are returned)
objects
Explicitly pass the objects to be tested (typically used with eventtable).
testonly
Set to true to return the objects, but not actually insert them into the database.
retry_realtime
Schedules realtime / batch credit card / electronic check / LEC billing events for for retry. Useful if card information has changed or manual retry is desired. The 'collect' method must be called to actually retry the transaction.
Implementation details: For either this customer, or for each of this customer's open invoices, changes the status of the first "done" (with statustext error) realtime processing event to "failed".
realtime_bop METHOD AMOUNT [ OPTION => VALUE ... ]
Runs a realtime credit card, ACH (electronic check) or phone bill transaction via a Business::OnlinePayment realtime gateway. See http://420.am/business-onlinepayment for supported gateways.
Available methods are: CC, ECHECK and LEC
Available options are: description, invnum, quiet, paynum_ref, payunique
The additional options payname, address1, address2, city, state, zip, payinfo and paydate are also available. Any of these options, if set, will override the value from the customer record.
description is a free-text field passed to the gateway. It defaults to "Internet services".
If an invnum is specified, this payment (if successful) is applied to the specified invoice. If you don't specify an invnum you might want to call the apply_payments method.
quiet can be set true to surpress email decline notices.
paynum_ref can be set to a scalar reference. It will be filled in with the resulting paynum, if any.
payunique is a unique identifier for this payment.
(moved from cust_bill) (probably should get realtime_{card,ach,lec} here too)
fake_bop; default_payment_gateway; remove_cvv
Removes the paycvv field from the database directly.
If there is an error, returns the error, otherwise returns false.
realtime_refund_bop METHOD [ OPTION => VALUE ... ]
Refunds a realtime credit card, ACH (electronic check) or phone bill transaction via a Business::OnlinePayment realtime gateway. See http://420.am/business-onlinepayment for supported gateways.
Available methods are: CC, ECHECK and LEC
Available options are: amount, reason, paynum, paydate
Most gateways require a reference to an original payment transaction to refund, so you probably need to specify a paynum.
amount defaults to the original amount of the payment if not specified.
reason specifies a reason for the refund.
paydate specifies the expiration date for a credit card overriding the value from the customer record or the payment record. Specified as yyyy-mm-dd
Implementation note: If amount is unspecified or equal to the amount of the orignal payment, first an attempt is made to "void" the transaction via the gateway (to cancel a not-yet settled transaction) and then if that fails, the normal attempt is made to "refund" ("credit") the transaction via the gateway is attempted.
  1. The additional options payname, address1, address2, city, state, #zip, payinfo and paydate are also available. Any of these options, #if set, will override the value from the customer record.
  1. If an invnum is specified, this payment (if successful) is applied to the #specified invoice. If you don't specify an invnum you might want to #call the apply_payments method.
batch_card OPTION => VALUE...
Adds a payment for this invoice to the pending credit card batch (see FS::cust_pay_batch), or, if the realtime option is set to a true value, runs the payment using a realtime gateway.
apply_payments_and_credits
Applies unapplied payments and credits.
In most cases, this new method should be used in place of sequential apply_payments and apply_credits methods.
If there is an error, returns the error, otherwise returns false.
apply_credits OPTION => VALUE ...
Applies (see FS::cust_credit_bill) unapplied credits (see FS::cust_credit) to outstanding invoice balances in chronological order (or reverse chronological order if the order option is set to newest) and returns the value of any remaining unapplied credits available for refund (see FS::cust_refund).
Dies if there is an error.
apply_payments
Applies (see FS::cust_bill_pay) unapplied payments (see FS::cust_pay) to outstanding invoice balances in chronological order.

#and returns the value of any remaining unapplied payments.

Dies if there is an error.
total_owed
Returns the total owed for this customer on all invoices (see "owed" in FS/cust bill|FS::cust_bill#owed|"owed" in FS::cust_bill).
total_owed_date TIME
Returns the total owed for this customer on all invoices with date earlier than TIME. TIME is specified as a UNIX timestamp; see "time" in perlfunc). Also see Time::Local and Date::Parse for conversion functions.
total_paid
Returns the total amount of all payments.
total_unapplied_credits
Returns the total outstanding credit (see FS::cust_credit) for this customer. See "credited" in FS/cust credit|FS::cust_credit#credited|"credited" in FS::cust_credit.
total_credited
Old name for total_unapplied_credits. Don't use.
total_unapplied_payments
Returns the total unapplied payments (see FS::cust_pay) for this customer. See "unapplied" in FS/cust pay|FS::cust_pay#unapplied|"unapplied" in FS::cust_pay.
total_unapplied_refunds
Returns the total unrefunded refunds (see FS::cust_refund) for this customer. See "unapplied" in FS/cust refund|FS::cust_refund#unapplied|"unapplied" in FS::cust_refund.
balance
Returns the balance for this customer (total_owed plus total_unrefunded, minus total_unapplied_credits minus total_unapplied_payments).
balance_date TIME
Returns the balance for this customer, only considering invoices with date earlier than TIME (total_owed_date minus total_credited minus total_unapplied_payments). TIME is specified as a UNIX timestamp; see "time" in perlfunc). Also see Time::Local and Date::Parse for conversion functions.
in_transit_payments
Returns the total of requests for payments for this customer pending in batches in transit to the bank. See FS::pay_batch and FS::cust_pay_batch
paydate_monthyear
Returns a two-element list consisting of the month and year of this customer's paydate (credit card expiration date for CARD customers)
invoicing_list [ ARRAYREF ]
If an arguement is given, sets these email addresses as invoice recipients (see FS::cust_main_invoice). Errors are not fatal and are not reported (except as warnings), so use check_invoicing_list first.
Returns a list of email addresses (with svcnum entries expanded).
Note: You can clear the invoicing list by passing an empty ARRAYREF. You can check it without disturbing anything by passing nothing.
This interface may change in the future.
check_invoicing_list ARRAYREF
Checks these arguements as valid input for the invoicing_list method. If there is an error, returns the error, otherwise returns false.
set_default_invoicing_list
Sets the invoicing list to all accounts associated with this customer, overwriting any previous invoicing list.
all_emails
Returns the email addresses of all accounts provisioned for this customer.
invoicing_list_addpost
Adds postal invoicing to this customer. If this customer is already configured to receive postal invoices, does nothing.
invoicing_list_emailonly
Returns the list of email invoice recipients (invoicing_list without non-email destinations such as POST and FAX).
invoicing_list_emailonly_scalar
Returns the list of email invoice recipients (invoicing_list without non-email destinations such as POST and FAX) as a comma-separated scalar.
referral_cust_main [ DEPTH [ EXCLUDE_HASHREF ] ]
Returns an array of customers referred by this customer (referral_custnum set to this custnum). If DEPTH is given, recurses up to the given depth, returning customers referred by customers referred by this customer and so on, inclusive. The default behavior is DEPTH 1 (no recursion).
referral_cust_main_ncancelled
Same as referral_cust_main, except only returns customers with uncancelled packages.
referral_cust_pkg [ DEPTH ]
Like referral_cust_main, except returns a flat list of all unsuspended (and uncancelled) packages for each customer. The number of items in this list may be useful for comission calculations (perhaps after a grep { my $pkgpart = $_-pkgpart; grep { $_ == $pkgpart } @commission_worthy_pkgparts> } $cust_main-> ).
referring_cust_main
Returns the single cust_main record for the customer who referred this customer (referral_custnum), or false.
credit AMOUNT, REASON [ , OPTION => VALUE ... ]
Applies a credit to this customer. If there is an error, returns the error, otherwise returns false.
REASON can be a text string, an FS::reason object, or a scalar reference to a reasonnum. If a text string, it will be automatically inserted as a new reason, and a 'reason_type' option must be passed to indicate the FS::reason_type for the new reason.
An addlinfo option may be passed to set the credit's addlinfo field.
Any other options are passed to FS::cust_credit::insert.
charge AMOUNT [ PKG [ COMMENT [ TAXCLASS ] ] ]
Creates a one-time charge for this customer. If there is an error, returns the error, otherwise returns false.
cust_bill
Returns all the invoices (see FS::cust_bill) for this customer.
open_cust_bill
Returns all the open (owed > 0) invoices (see FS::cust_bill) for this customer.
cust_credit
Returns all the credits (see FS::cust_credit) for this customer.
cust_pay
Returns all the payments (see FS::cust_pay) for this customer.
cust_pay_void
Returns all voided payments (see FS::cust_pay_void) for this customer.
cust_pay_batch
Returns all batched payments (see FS::cust_pay_void) for this customer.
cust_refund
Returns all the refunds (see FS::cust_refund) for this customer.
display_custnum
Returns the displayed customer number for this customer: agent_custid if cust_main-default_agent_custid is set and it has a value, custnum otherwise.
name
Returns a name string for this customer, either "Company (Last, First)" or "Last, First".
ship_name
Returns a name string for this (service/shipping) contact, either "Company (Last, First)" or "Last, First".
name_short
Returns a name string for this customer, either "Company" or "First Last".
ship_name_short
Returns a name string for this (service/shipping) contact, either "Company" or "First Last".
contact
Returns this customer's full (billing) contact name only, "Last, First"
ship_contact
Returns this customer's full (shipping) contact name only, "Last, First"
contact_firstlast
Returns this customers full (billing) contact name only, "First Last".
ship_contact_firstlast
Returns this customer's full (shipping) contact name only, "First Last".
country_full
Returns this customer's full country name
geocode DATA_VENDOR
Returns a value for the customer location as encoded by DATA_VENDOR. Currently this only makes sense for "CCH" as DATA_VENDOR.
cust_status; status
Returns a status string for this customer, currently:
prospect - No packages have ever been ordered
; active - One or more recurring packages is active:; inactive - No active recurring packages, but otherwise unsuspended/uncancelled (the inactive status is new - previously inactive customers were mis-identified as cancelled):; suspended - All non-cancelled recurring packages are suspended:; cancelled - All recurring packages are cancelled; ucfirst_cust_status; ucfirst_status
Returns the status with the first character capitalized.
statuscolor
Returns a hex triplet color string for this customer's status.
tickets
Returns an array of hashes representing the customer's RT tickets.

CLASS METHODS

statuses
Class method that returns the list of possible status strings for customers (see the status method). For example:

 @statuses = FS::cust_main->statuses();

prospect_sql
Returns an SQL expression identifying prospective cust_main records (customers with no packages ever ordered)
active_sql
Returns an SQL expression identifying active cust_main records (customers with active recurring packages).
inactive_sql
Returns an SQL expression identifying inactive cust_main records (customers with no active recurring packages, but otherwise unsuspended/uncancelled).
susp_sql =item suspended_sql
Returns an SQL expression identifying suspended cust_main records.
cancel_sql =item cancelled_sql
Returns an SQL expression identifying cancelled cust_main records.
uncancel_sql =item uncancelled_sql
Returns an SQL expression identifying un-cancelled cust_main records.
balance_sql
Returns an SQL fragment to retreive the balance.
balance_date_sql START_TIME [ END_TIME [ OPTION => VALUE ... ] ]
Returns an SQL fragment to retreive the balance for this customer, only considering invoices with date earlier than START_TIME, and optionally not later than END_TIME (total_owed_date minus total_unapplied_credits minus total_unapplied_payments).
Times are specified as SQL fragments or numeric UNIX timestamps; see "time" in perlfunc). Also see Time::Local and Date::Parse for conversion functions. The empty string can be passed to disable that time constraint completely.
Available options are:
unapplied_date
set to true to disregard unapplied credits, payments and refunds outside the specified time period - by default the time period restriction only applies to invoices (useful for reporting, probably a bad idea for event triggering)
total
(unused. obsolete?) set to true to remove all customer comparison clauses, for totals
where
(unused. obsolete?) WHERE clause hashref (elements "AND"ed together) (typically used with the total option)
join
(unused. obsolete?) JOIN clause (typically used with the total option)
_money_table_where TABLE START_TIME [ END_TIME [ OPTION => VALUE ... ] ]
Helper method for balance_date_sql; name (and usage) subject to change (suggestions welcome).
Returns a WHERE clause for the specified monetary TABLE (cust_bill, cust_refund, cust_credit or cust_pay).
If TABLE is "cust_bill" or the unapplied_date option is true, only considers records with date earlier than START_TIME, and optionally not later than END_TIME .
search_sql HASHREF
(Class method)
Returns a qsearch hash expression to search for parameters specified in HREF. Valid parameters are
agentnum
; status:; cancelled_pkgs
bool
signupdate
listref of start date, end date
payby
listref
current_balance
listref (list returned by FS::UI::Web::parse_lt_gt($cgi, 'current_balance'))
cust_fields
; flattened_pkgs
bool
email_search_sql HASHREF
(Class method)
Emails a notice to the specified customers.
Valid parameters are those of the search_sql method, plus the following:
from
From: address
subject
Email Subject:
html_body
HTML body
text_body
Text body
job
Optional job queue job for status updates.
Returns an error message, or false for success.
If an error occurs during any email, stops the enture send and returns that error. Presumably if you're getting SMTP errors aborting is better than retrying everything.
fuzzy_search FUZZY_HASHREF [ HASHREF, SELECT, EXTRA_SQL, CACHE_OBJ ]
Performs a fuzzy (approximate) search and returns the matching FS::cust_main records. Currently, first, last and/or company may be specified (the appropriate ship_ field is also searched).
Additional options are the same as FS::Record::qsearch
masked FIELD
Returns a masked version of the named field

SUBROUTINES

smart_search OPTION => VALUE ...
Accepts the following options: search, the string to search for. The string will be searched for as a customer number, phone number, name or company name, as an exact, or, in some cases, a substring or fuzzy match (see the source code for the exact heuristics used); no_fuzzy_on_exact, causes smart_search to skip fuzzy matching when an exact match is found.
Any additional options are treated as an additional qualifier on the search (i.e. agentnum).
Returns a (possibly empty) array of FS::cust_main objects.
email_search
Accepts the following options: email, the email address to search for. The email address will be searched for as an email invoice destination and as an svc_acct account.
  1. Any additional options are treated as an additional qualifier on the search #(i.e. agentnum).
Returns a (possibly empty) array of FS::cust_main objects (but usually just none or one).
check_and_rebuild_fuzzyfiles; rebuild_fuzzyfiles; all_X; append_fuzzyfiles LASTNAME COMPANY; batch_charge; notify CUSTOMER_OBJECT TEMPLATE_NAME OPTIONS
Sends a templated email notification to the customer (see Text::Template).
OPTIONS is a hash and may include
from - the email sender (default is invoice_from)
to - comma-separated scalar or arrayref of recipients (default is invoicing_list)
subject - The subject line of the sent email notification (default is "Notice from company_name")
extra_fields - a hashref of name/value pairs which will be substituted into the template
The following variables are vavailable in the template.
$first - the customer first name $last - the customer last name $company - the customer company $payby - a description of the method of payment for the customer # would be nice to use FS::payby::shortname $payinfo - the account information used to collect for this customer $expdate - the expiration of the customer payment in seconds from epoch
generate_letter CUSTOMER_OBJECT TEMPLATE_NAME OPTIONS
Generates a templated notification to the customer (see Text::Template).
OPTIONS is a hash and may include
extra_fields - a hashref of name/value pairs which will be substituted into the template. These values may override values mentioned below and those from the customer record.
The following variables are available in the template instead of or in addition to the fields of the customer record.
$payby - a description of the method of payment for the customer # would be nice to use FS::payby::shortname $payinfo - the masked account information used to collect for this customer $expdate - the expiration of the customer payment method in seconds from epoch $returnaddress - the return address defaults to invoice_latexreturnaddress or company_address
print_ps TEMPLATE
Returns an postscript letter filled in from TEMPLATE, as a scalar.
print TEMPLATE
Prints the filled in template.
TEMPLATE is the name of a Text::Template to fill in and print.

BUGS

The delete method.

The delete method should possibly take an FS::cust_main object reference instead of a scalar customer number.

Bill and collect options should probably be passed as references instead of a list.

There should probably be a configuration file with a list of allowed credit card types.

No multiple currency support (probably a larger project than just this module).

payinfo_masked false laziness with cust_pay.pm and cust_refund.pm

Birthdates rely on negative epoch values.

The payby for card/check batches is broken. With mixed batching, bad things will happen.

collect invoice_time should be renamed time, like bill.

SEE ALSO

FS::Record, FS::cust_pkg, FS::cust_bill, FS::cust_credit FS::agent, FS::part_referral, FS::cust_main_county, FS::cust_main_invoice, FS::UID, schema.html from the base documentation.