Freeside:4:Documentation:Developer/FS/cust main

From Freeside
< Freeside:4:Documentation:Developer‎ | FS
Revision as of 08:20, 18 November 2015 by Jeremyd (talk | contribs) (Edit via perl MediaWiki framework (1.13))

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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)
daytime
phone (optional)
night
phone (optional)
fax
phone (optional)
mobile
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'
usernum
Order taker (see FS::access_user)
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'
edit_subject
Allow self-service editing of ticket subjects, empty or 'Y'
calling_list_exempt
Do not call, empty or 'Y'
invoice_ship_address
Display ship_address ("Service address") on invoices for this customer, 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.
Usually the customer's location will not yet exist in the database, and the bill_location and ship_location pseudo-fields must be set to uninserted FS::cust_location objects. These will be inserted and linked (in both directions) to the new customer record. If they're references to the same object, they will become the same location.
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, noexport, tax_exemption, prospectnum, contact and contact_params.
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.)
The tax_exemption option can be set to an arrayref of tax names or a hashref of tax names and exemption numbers. FS::cust_main_exemption records will be created and inserted.
If prospectnum is set, moves contacts and locations from that prospect.
If contact is set to an arrayref of FS::contact objects, inserts those new contacts with this new customer.
If contact_params is set to a hashref of CGI parameters (and contact is unset), inserts those new contacts with this new customer. Handles CGI paramaters for an "m2" multiple entry field as passed by edit/cust_main.cgi
If cust_payby_params is set to a hashref o fCGI parameters, inserts those new stored payment records with this new customer. Handles CGI parameters for an "m2" multiple entry field as passed by edit/cust_main.cgi
PACKAGE METHODS
Documentation on customer package methods has been moved to FS::cust_main::Packages.
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, five scalar references can be passed as well. They will have their values filled in with the amount, number of seconds, and number of upload, download, and total bytes applied by this prepaid card.
get_prepay IDENTIFIER | PREPAY_CREDIT_OBJ [ , OPTION => VALUE ... ]
Looks up and deletes a prepaid card (see FS::prepay_credit), specified either by identifier or as an FS::prepay_credit object.
Available options are: amount_ref, seconds_ref, upbytes_ref, downbytes_ref, and totalbytes_ref. The scalars (provided by references) 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.
delete [ OPTION => VALUE ... ]
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, as the "new_customer" option. 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 at "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), statements (see FS::cust_statement), credits (see FS::cust_credit), payments (see FS::cust_pay) or refunds (see FS::cust_refund), unless you set the "delete_financials" option to a true value.
replace [ OLD_RECORD ] [ INVOICING_LIST_ARYREF ] [ , OPTION => VALUE ... ] ]
Replaces the OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
To change the customer's address, set the pseudo-fields bill_location and ship_location. The address will still only change if at least one of the address fields differs from the existing values.
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' ] );

Currently available options are: tax_exemption.
The tax_exemption option can be set to an arrayref of tax names or a hashref of tax names and exemption numbers. FS::cust_main_exemption records will be deleted and inserted as appropriate.
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.
replace_check
Additional checks for replace only.
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.
location_hash
Returns a list of key/value pairs, with the following keys: address1, adddress2, city, county, state, zip, country, district, and geocode. The shipping address is used if present.
cust_location
Returns all locations (see FS::cust_location) for this customer.
cust_contact
Returns all contact associations (see FS::cust_contact) for this customer.
cust_payby
Returns all payment methods (see FS::cust_payby) for this customer.
unsuspend
Unsuspends all unflagged suspended packages (see "unflagged_suspended_pkgs" and FS::cust_pkg) for this customer, except those on hold.
Returns a list: an empty list on success or a list of errors.
release_hold
Unsuspends all suspended packages in the on-hold state (those without setup dates) for this customer.
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.:; nobill - can be set true to skip billing if it might otherwise be done.
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.
agent_name
Returns the agent name (see FS::agent) for this customer.
cust_tag
Returns any tags associated with this customer, as FS::cust_tag objects, or an empty list if there are no tags.
part_tag
Returns any tags associated with this customer, as FS::part_tag objects, or an empty list if there are no tags.
cust_class
Returns the customer class, as an FS::cust_class object, or the empty string if there is no customer class.
categoryname
Returns the customer category name, or the empty string if there is no customer category.
classname
Returns the customer class name, or the empty string if there is no customer class.
tax_status
Returns the external tax status, as an FS::tax_status object, or the empty string if there is no tax status.
taxstatus
Returns the tax status code if there is one.
BILLING METHODS
Documentation on billing methods has been moved to FS::cust_main::Billing.
REALTIME BILLING METHODS
Documentation on realtime billing methods has been moved to FS::cust_main::Billing_Realtime.
remove_cvv
Removes the paycvv field from the database directly.
If there is an error, returns the error, otherwise returns false.
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_owed_pkgnum PKGNUM
Returns the total owed on all invoices for this customer's specific package when using experimental package balances (see "owed pkgnum" in FS/cust bill|FS::cust_bill#owed_pkgnum|"owed_pkgnum" in FS::cust_bill).
total_owed_date_pkgnum TIME PKGNUM
Returns the total owed for this customer's specific package when using experimental package balances 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_credits_pkgnum PKGNUM
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_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_payments_pkgnum PKGNUM
Returns the total unapplied payments (see FS::cust_pay) for this customer's specific package when using experimental package balances. 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.
balance_date_range [ START_TIME [ END_TIME [ OPTION => VALUE ... ] ] ]
Returns the balance for this customer, optionally considering invoices with date earlier than START_TIME, and 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.
Accepts the same options as balance_date_sql:
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)
cutoff
An absolute cutoff time. Payments, credits, and refunds applied after this time will be ignored. Note that START_TIME and END_TIME only limit the date range for invoices and unapplied payments, credits, and refunds.
balance_pkgnum PKGNUM
Returns the balance for this customer's specific package when using experimental package balances (total_owed plus total_unrefunded, minus total_unapplied_credits minus total_unapplied_payments)
payment_info
Returns a hash of useful information for making a payment.
balance
Current balance.
payby
'CARD' (credit card - automatic), 'DCRD' (credit card - on-demand), 'CHEK' (electronic check - automatic), 'DCHK' (electronic check - on-demand), 'LECB' (Phone bill billing), 'BILL' (billing), or 'COMP' (free).
For credit card transactions:
card_type 1
; payname
Exact name on card
For electronic check transactions:
stateid_state; 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)
paydate_epoch
Returns the exact time in seconds corresponding to the payment method expiration date. For CARD/DCRD customers this is the end of the month; for others (COMP is the only other payby that uses paydate) it's the start. Returns 0 if the paydate is empty or set to the far future.
paydate_epoch_sql
Class method. Returns an SQL expression to obtain the payment expiration date as a number of seconds.
tax_exemption TAXNAME; cust_main_exemption; 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_custnum_cust_main
Returns the customer who referred this customer (or the empty string, if this customer was not referred).
Note the difference with referral_cust_main method: This method, referral_custnum_cust_main returns the single customer (if any) who referred this customer, while referral_cust_main returns an array of customers referred BY this customer.
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).
Note the difference with referral_custnum_cust_main method: This method, referral_cust_main, returns an array of customers referred BY this customer, while referral_custnum_cust_main returns the single customer (if any) who referred this customer.
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 commission 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. Likewise for eventnum, commission_agentnum, commission_salesnum and commission_pkgnum.
Any other options are passed to FS::cust_credit::insert.
charge HASHREF || AMOUNT [ PKG [ COMMENT [ TAXCLASS ] ] ]
Creates a one-time charge for this customer. If there is an error, returns the error, otherwise returns false.
New-style, with a hashref of options:

 my $error = $cust_main->charge(
                                 {
                                   'amount'     => 54.32,
                                   'quantity'   => 1,
                                   'start_date' => str2time('7/4/2009'),
                                   'pkg'        => 'Description',
                                   'comment'    => 'Comment',
                                   'additional' => [], #extra invoice detail
                                   'classnum'   => 1,  #pkg_class

                                   'setuptax'   => '', # or 'Y' for tax exempt

                                   'locationnum'=> 1234, # optional

                                   #internal taxation
                                   'taxclass'   => 'Tax class',

                                   #vendor taxation
                                   'taxproduct' => 2,  #part_pkg_taxproduct
                                   'override'   => {}, #XXX describe

                                   #will be filled in with the new object
                                   'cust_pkg_ref' => \$cust_pkg,

                                   #generate an invoice immediately
                                   'bill_now' => 0,
                                   'invoice_terms' => '', #with these terms
                                 }
                               );

Old-style:

 my $error = $cust_main->charge( 54.32, 'Description', 'Comment', 'Tax class' );

cust_bill [ OPTION => VALUE... | EXTRA_QSEARCH_PARAMS_HASHREF ]
Returns all the invoices (see FS::cust_bill) for this customer.
Optionally, a list or hashref of additional arguments to the qsearch call can be passed.
open_cust_bill
Returns all the open (owed > 0) invoices (see FS::cust_bill) for this customer.
legacy_cust_bill [ OPTION => VALUE... | EXTRA_QSEARCH_PARAMS_HASHREF ]
Returns all the legacy invoices (see FS::legacy_cust_bill) for this customer.
cust_statement [ OPTION => VALUE... | EXTRA_QSEARCH_PARAMS_HASHREF ]
Returns all the statements (see FS::cust_statement) for this customer.
Optionally, a list or hashref of additional arguments to the qsearch call can be passed.
cust_bill_void
Returns all the voided invoices (see FS::cust_bill_void) for this customer.
svc_x SVCDB [ OPTION => VALUE | EXTRA_QSEARCH_PARAMS_HASHREF ]
Returns all services of type SVCDB (such as 'svc_acct') for this customer.
Optionally, a list or hashref of additional arguments to the qsearch call can be passed following the SVCDB.
cust_credit
Returns all the credits (see FS::cust_credit) for this customer.
cust_credit_pkgnum
Returns all the credits (see FS::cust_credit) for this customer's specific package when using experimental package balances.
cust_credit_void
Returns all voided credits (see FS::cust_credit_void) for this customer.
cust_pay
Returns all the payments (see FS::cust_pay) for this customer.
num_cust_pay
Returns the number of payments (see FS::cust_pay) for this customer. Also called automatically when the cust_pay method is used in a scalar context.
unapplied_cust_pay
Returns all the unapplied payments (see FS::cust_pay) for this customer.
cust_pay_pkgnum
Returns all the payments (see FS::cust_pay) for this customer's specific package when using experimental package balances.
cust_pay_void
Returns all voided payments (see FS::cust_pay_void) for this customer.
cust_pay_pending
Returns all pending payments (see FS::cust_pay_pending) for this customer (without status "done").
cust_pay_pending_attempt
Returns all payment attempts / declined payments for this customer, as pending payments objects (see FS::cust_pay_pending), with status "done" but without a corresponding payment (see FS::cust_pay).
num_cust_pay_pending
Returns the number of pending payments (see FS::cust_pay_pending) for this customer (without status "done"). Also called automatically when the cust_pay_pending method is used in a scalar context.
num_cust_pay_pending_attempt
Returns the number of pending payments (see FS::cust_pay_pending) for this customer, with status "done" but without a corresp. Also called automatically when the cust_pay_pending method is used in a scalar context.
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".
service_contact
Returns the FS::contact object for this customer that has the 'Service' contact class, or undef if there is no such contact. Deprecated; don't use this in new code.
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".
county_state_county [ PREFIX ]
Returns a string consisting of just the county, state and country.
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. Displayed as "No packages".
ordered
Recurring packages all are new (not yet billed).
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.
Behavior of inactive vs. cancelled edge cases can be adjusted with the cust_main-status_module configuration option.
is_status_delay_cancel
Returns true if customer status is 'suspended' and all suspended cust_pkg return true for cust_pkg->is_status_delay_cancel.
This is not a real status, this only meant for hacking display values, because otherwise treating the customer as suspended is really the whole point of the delay_cancel option.
ucfirst_cust_status; ucfirst_status
Deprecated, use the cust_status_label method instead.
Returns the status with the first character capitalized.
cust_status_label; status_label
Returns the display label for this status.
statuscolor
Returns a hex triplet color string for this customer's status.
tickets [ STATUS ]
Returns an array of hashes representing the customer's RT tickets.
An optional status (or arrayref or hashref of statuses) may be specified.
appointments [ STATUS ]
Returns an array of hashes representing the customer's RT tickets which are appointments.
masked FIELD
Returns a masked version of the named field
payment_history
Returns an array of hashrefs standardizing information from cust_bill, cust_pay, cust_credit and cust_refund objects. Each hashref has the following fields:
type - one of 'Line item', 'Invoice', 'Payment', 'Credit', 'Refund' or 'Previous'
date - value of _date field, unix timestamp
date_pretty - user-friendly date
description - user-friendly description of item
amount - impact of item on user's balance (positive for Invoice/Refund/Line item, negative for Payment/Credit.) Not to be confused with the native 'amount' field in cust_credit, see below.
amount_pretty - includes money char
balance - customer balance, chronologically as of this item
balance_pretty - includes money char
charged - amount charged for cust_bill (Invoice or Line item) records, undef for other types
paid - amount paid for cust_pay records, undef for other types
credit - amount credited for cust_credit records, undef for other types. Literally the 'amount' field from cust_credit, renamed here to avoid confusion.
refund - amount refunded for cust_refund records, undef for other types
The four table-specific keys always have positive values, whether they reflect charges or payments.
The following options may be passed to this method:
line_items - if true, returns charges ('Line item') rather than invoices
start_date - unix timestamp, only include records on or after. If specified, an item of type 'Previous' will also be included. It does not have table-specific fields.
end_date - unix timestamp, only include records before
reverse_sort - order from newest to oldest (default is oldest to newest)
conf - optional already-loaded FS::Conf object.

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();

cust_status_sql
Returns an SQL fragment to determine the status of a cust_main record, as a string.
prospect_sql
Returns an SQL expression identifying prospective cust_main records (customers with no packages ever ordered)
ordered_sql
Returns an SQL expression identifying ordered cust_main records (customers with no active packages, but recurring packages not yet setup or one time charges not yet billed).
active_sql
Returns an SQL expression identifying active cust_main records (customers with active recurring packages).
none_active_sql
Returns an SQL expression identifying cust_main records with no active recurring packages. This includes customers of status prospect, ordered, inactive, and suspended.
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, optionally considering invoices with date earlier than START_TIME, and 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)
cutoff
An absolute cutoff time. Payments, credits, and refunds applied after this time will be ignored. Note that START_TIME and END_TIME only limit the date range for invoices and unapplied payments, credits, and refunds.
unapplied_payments_date_sql START_TIME [ END_TIME ]
Returns an SQL fragment to retreive the total unapplied payments for this customer, only considering payments with date earlier than START_TIME, and optionally not later than END_TIME.
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:
_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 .

SUBROUTINES

  1. =item notify CUSTOMER_OBJECT TEMPLATE_NAME OPTIONS
  1. Deprecated. Use event notification and message templates #(FS::msg_template) instead.
  1. Sends a templated email notification to the customer (see Text::Template).
  1. OPTIONS is a hash and may include
  1. from - the email sender (default is invoice_from)
  1. to - comma-separated scalar or arrayref of recipients # (default is invoicing_list)
  1. subject - The subject line of the sent email notification # (default is "Notice from company_name")
  1. extra_fields - a hashref of name/value pairs which will be substituted # into the template
  1. The following variables are vavailable in the template.
  1. $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
  1. =cut
  1. sub notify { # my ($self, $template, %options) = @_;
  1. return unless $conf->exists($template);
  1. my $from = $conf->invoice_from_full($self->agentnum) # if $conf->exists('invoice_from', $self->agentnum); # $from = $options{from} if exists($options{from});
  1. my $to = join(',', $self->invoicing_list_emailonly); # $to = $options{to} if exists($options{to}); # # my $subject = "Notice from " . $conf->config('company_name', $self->agentnum) # if $conf->exists('company_name', $self->agentnum); # $subject = $options{subject} if exists($options{subject});
  1. my $notify_template = new Text::Template (TYPE => 'ARRAY', # SOURCE => [ map "$_\n", # $conf->config($template)] # ) # or die "can't create new Text::Template object: Text::Template::ERROR"; # $notify_template->compile() # or die "can't compile template: Text::Template::ERROR";
  1. $FS::notify_template::_template::company_name = # $conf->config('company_name', $self->agentnum); # $FS::notify_template::_template::company_address = # join("\n", $conf->config('company_address', $self->agentnum) ). "\n";
  1. my $paydate = $self->paydate || '2037-12-31'; # $FS::notify_template::_template::first = $self->first; # $FS::notify_template::_template::last = $self->last; # $FS::notify_template::_template::company = $self->company; # $FS::notify_template::_template::payinfo = $self->mask_payinfo; # my $payby = $self->payby; # my ($payyear,$paymonth,$payday) = split (/-/,$paydate); # my $expire_time = timelocal(0,0,0,$payday,--$paymonth,$payyear);
  1. #credit cards expire at the end of the month/year of their exp date # if ($payby eq 'CARD' || $payby eq 'DCRD') { # $FS::notify_template::_template::payby = 'credit card'; # ($paymonth < 11) ? $paymonth++ : ($paymonth=0, $payyear++); # $expire_time = timelocal(0,0,0,$payday,$paymonth,$payyear); # $expire_time--; # }elsif ($payby eq 'COMP') { # $FS::notify_template::_template::payby = 'complimentary account'; # }else{ # $FS::notify_template::_template::payby = 'current method'; # } # $FS::notify_template::_template::expdate = $expire_time;
  1. for (keys %{$options{extra_fields}}){ # no strict "refs"; # ${"FS::notify_template::_template::$_"} = $options{extra_fields}->{$_}; # }
  1. send_email(from => $from, # to => $to, # subject => $subject, # body => $notify_template->fill_in( PACKAGE => # 'FS::notify_template::_template' ), # );
  1. }
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.
template_text - if present, ignores TEMPLATE_NAME and uses the provided text
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.
queued_bill 'custnum' => CUSTNUM [ , OPTION => VALUE ... ]
Subroutine (not a method), designed to be called from the queue.
Takes a list of options and values.
Pulls up the customer record via the custnum option and calls bill_and_collect.
queued_collect 'custnum' => CUSTNUM [ , OPTION => VALUE ... ]
Like queued_bill, but instead of bill_and_collect, just runs the collect part. This is used in batch tax calculation, where invoice generation and collection events have to be completely separated.

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.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 4610:
You can't have =items (as at line 4709) unless the first thing after the =over is an =item