Freeside:1.7:Documentation:Developer/FS/cust bill

From Freeside
Jump to: navigation, search

NAME

FS::cust_bill - Object methods for cust_bill records

SYNOPSIS

 use FS::cust_bill;

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

 $error = $record->insert;

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

 $error = $record->delete;

 $error = $record->check;

 ( $total_previous_balance, @previous_cust_bill ) = $record->previous;

 @cust_bill_pkg_objects = $cust_bill->cust_bill_pkg;

 ( $total_previous_credits, @previous_cust_credit ) = $record->cust_credit;

 @cust_pay_objects = $cust_bill->cust_pay;

 $tax_amount = $record->tax;

 @lines = $cust_bill->print_text;
 @lines = $cust_bill->print_text $time;

DESCRIPTION

An FS::cust_bill object represents an invoice; a declaration that a customer owes you money. The specific charges are itemized as cust_bill_pkg records (see FS::cust_bill_pkg). FS::cust_bill inherits from FS::Record. The following fields are currently supported:

invnum - primary key (assigned automatically for new invoices); custnum - customer (see FS::cust_main); _date - specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.; charged - amount of this invoice; printed - deprecated; closed - books closed flag, empty or `Y'

METHODS

new HASHREF
Creates a new invoice. To add the invoice to the database, see "insert". Invoices are normally created by calling the bill method of a customer object (see FS::cust_main).
insert
Adds this invoice to the database ("Posts" the invoice). If there is an error, returns the error, otherwise returns false.
delete
This method now works but you probably shouldn't use it. Instead, apply a credit against the invoice.
Using this method to delete invoices outright is really, really bad. There would be no record you ever posted this invoice, and there are no check to make sure charged = 0 or that there are no associated cust_bill_pkg records.
Really, don't use it.
replace OLD_RECORD
Replaces the OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
Only printed may be changed. printed is normally updated by calling the collect method of a customer object (see FS::cust_main).
check
Checks all fields to make sure this is a valid invoice. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
previous
Returns a list consisting of the total previous balance for this customer, followed by the previous outstanding invoices (as FS::cust_bill objects also).
cust_bill_pkg
Returns the line items (see FS::cust_bill_pkg) for this invoice.
cust_pkg
Returns the packages (see FS::cust_pkg) corresponding to the line items for this invoice.
open_cust_bill_pkg
Returns the open line items for this invoice.
Note that cust_bill_pkg with both setup and recur fees are returned as two separate line items, each with only one fee.
cust_bill_event
Returns the completed invoice events (see FS::cust_bill_event) for this invoice.
cust_main
Returns the customer (see FS::cust_main) for this invoice.
cust_suspend_if_balance_over AMOUNT
Suspends the customer associated with this invoice if the total amount owed on this invoice and all older invoices is greater than the specified amount.
Returns a list: an empty list on success or a list of errors.
cust_credit
Depreciated. See the cust_credited method.

#Returns a list consisting of the total previous credited (see
#L<FS::cust_credit>) and unapplied for this customer, followed by the previous
#outstanding credits (FS::cust_credit objects).

cust_pay
Depreciated. See the cust_bill_pay method.
  1. Returns all payments (see FS::cust_pay) for this invoice.
cust_bill_pay
Returns all payment applications (see FS::cust_bill_pay) for this invoice.
cust_credited
Returns all applied credits (see FS::cust_credit_bill) for this invoice.
tax
Returns the tax amount (see FS::cust_bill_pkg) for this invoice.
owed
Returns the amount owed (still outstanding) on this invoice, which is charged minus all payment applications (see FS::cust_bill_pay) and credit applications (see FS::cust_credit_bill).
apply_payments_and_credits; generate_email PARAMHASH
PARAMHASH can contain the following:
from => sender address, required
; tempate => alternate template name, optional:; print_text => text attachment arrayref, optional:; subject => email subject, optional
Returns an argument list to be passed to FS::Misc::send_email.
mimebuild_pdf
Returns a list suitable for passing to MIME::Entity->build(), representing this invoice as PDF attachment.
send [ TEMPLATENAME [ , AGENTNUM [ , INVOICE_FROM ] ] ]
Sends this invoice to the destinations configured for this customer: sends email, prints and/or faxes. See FS::cust_main_invoice.
TEMPLATENAME, if specified, is the name of a suffix for alternate invoices.
AGENTNUM, if specified, means that this invoice will only be sent for customers of the specified agent or agent(s). AGENTNUM can be a scalar agentnum (for a single agent) or an arrayref of agentnums.
INVOICE_FROM, if specified, overrides the default email invoice From: address.
AMOUNT, if specified, only sends the invoice if the total amount owed on this invoice and all older invoices is greater than the specified amount.
email [ TEMPLATENAME [ , INVOICE_FROM ] ]
Emails this invoice.
TEMPLATENAME, if specified, is the name of a suffix for alternate invoices.
INVOICE_FROM, if specified, overrides the default email invoice From: address.
lpr_data [ TEMPLATENAME ]
Returns the postscript or plaintext for this invoice as an arrayref.
TEMPLATENAME, if specified, is the name of a suffix for alternate invoices.
print [ TEMPLATENAME ]
Prints this invoice.
TEMPLATENAME, if specified, is the name of a suffix for alternate invoices.
fax_invoice [ TEMPLATENAME ]
Faxes this invoice.
TEMPLATENAME, if specified, is the name of a suffix for alternate invoices.
ftp_invoice [ TEMPLATENAME ]
Sends this invoice data via FTP.
TEMPLATENAME is unused?
spool_invoice [ TEMPLATENAME ]
Spools this invoice data (see FS::spool_csv)
TEMPLATENAME is unused?
send_if_newest [ TEMPLATENAME [ , AGENTNUM [ , INVOICE_FROM ] ] ]
Like send, but only sends the invoice if it is the newest open invoice for this customer.
send_csv OPTION => VALUE, ...
Sends invoice as a CSV data-file to a remote host with the specified protocol.
Options are:
protocol - currently only "ftp" server username password dir
The file will be named "N-YYYYMMDDHHMMSS.csv" where N is the invoice number and YYMMDDHHMMSS is a timestamp.
See "print_csv" for a description of the output format.
spool_csv
Spools CSV invoice data.
Options are:
format - 'default' or 'billco'
; dest - if set (to POST, EMAIL or FAX), only sends spools invoices if the customer has the corresponding invoice destinations set (see FS::cust_main_invoice).:; agent_spools - if set to a true value, will spool to per-agent files rather than a single global file:; balanceover - if set, only spools the invoice if the total amount owed on this invoice and all older invoices is greater than the specified amount.; print_csv OPTION => VALUE, ...
Returns CSV data for this invoice.
Options are:
format - 'default' or 'billco'
Returns a list consisting of two scalars. The first is a single line of CSV header information for this invoice. The second is one or more lines of CSV detail information for this invoice.
If format is not specified or "default", the fields of the CSV file are as follows:
record_type, invnum, custnum, _date, charged, first, last, company, address1, address2, city, state, zip, country, pkg, setup, recur, sdate, edate
record type - record_type is either cust_bill or cust_bill_pkg
record_type is cust_bill for the initial header line only. The last five fields (pkg through edate) are irrelevant, and all other fields are filled in.
record_type is cust_bill_pkg for detail lines. Only the first two fields (record_type and invnum) and the last five fields (pkg through edate) are filled in.
invnum - invoice number
; custnum - customer number:; _date - invoice date:; charged - total invoice amount:; first - customer first name:; last - customer first name:; company - company name:; address1 - address line 1:; address2 - address line 1:; city:; state:; zip:; country:; pkg - line item description:; setup - line item setup fee (one or both of setup and recur will be defined):; recur - line item recurring fee (one or both of setup and recur will be defined):; sdate - start date for recurring fee:; edate - end date for recurring fee
If format is "billco", the fields of the header CSV file are as follows:

 +-------------------------------------------------------------------+
 |                        FORMAT HEADER FILE                         |
 |-------------------------------------------------------------------|
 | Field | Description                   | Name       | Type | Width |
 | 1     | N/A-Leave Empty               | RC         | CHAR |     2 |
 | 2     | N/A-Leave Empty               | CUSTID     | CHAR |    15 |
 | 3     | Transaction Account No        | TRACCTNUM  | CHAR |    15 |
 | 4     | Transaction Invoice No        | TRINVOICE  | CHAR |    15 |
 | 5     | Transaction Zip Code          | TRZIP      | CHAR |     5 |
 | 6     | Transaction Company Bill To   | TRCOMPANY  | CHAR |    30 |
 | 7     | Transaction Contact Bill To   | TRNAME     | CHAR |    30 |
 | 8     | Additional Address Unit Info  | TRADDR1    | CHAR |    30 |
 | 9     | Bill To Street Address        | TRADDR2    | CHAR |    30 |
 | 10    | Ancillary Billing Information | TRADDR3    | CHAR |    30 |
 | 11    | Transaction City Bill To      | TRCITY     | CHAR |    20 |
 | 12    | Transaction State Bill To     | TRSTATE    | CHAR |     2 |
 | 13    | Bill Cycle Close Date         | CLOSEDATE  | CHAR |    10 |
 | 14    | Bill Due Date                 | DUEDATE    | CHAR |    10 |
 | 15    | Previous Balance              | BALFWD     | NUM* |     9 |
 | 16    | Pmt/CR Applied                | CREDAPPLY  | NUM* |     9 |
 | 17    | Total Current Charges         | CURRENTCHG | NUM* |     9 |
 | 18    | Total Amt Due                 | TOTALDUE   | NUM* |     9 |
 | 19    | Total Amt Due                 | AMTDUE     | NUM* |     9 |
 | 20    | 30 Day Aging                  | AMT30      | NUM* |     9 |
 | 21    | 60 Day Aging                  | AMT60      | NUM* |     9 |
 | 22    | 90 Day Aging                  | AMT90      | NUM* |     9 |
 | 23    | Y/N                           | AGESWITCH  | CHAR |     1 |
 | 24    | Remittance automation         | SCANLINE   | CHAR |   100 |
 | 25    | Total Taxes & Fees            | TAXTOT     | NUM* |     9 |
 | 26    | Customer Reference Number     | CUSTREF    | CHAR |    15 |
 | 27    | Federal Tax***                | FEDTAX     | NUM* |     9 |
 | 28    | State Tax***                  | STATETAX   | NUM* |     9 |
 | 29    | Other Taxes & Fees***         | OTHERTAX   | NUM* |     9 |
 +-------+-------------------------------+------------+------+-------+

If format is "billco", the fields of the detail CSV file are as follows:

                                 FORMAT FOR DETAIL FILE
       |                            |           |      |
 Field | Description                | Name      | Type | Width
 1     | N/A-Leave Empty            | RC        | CHAR |     2
 2     | N/A-Leave Empty            | CUSTID    | CHAR |    15
 3     | Account Number             | TRACCTNUM | CHAR |    15
 4     | Invoice Number             | TRINVOICE | CHAR |    15
 5     | Line Sequence (sort order) | LINESEQ   | NUM  |     6
 6     | Transaction Detail         | DETAILS   | CHAR |   100
 7     | Amount                     | AMT       | NUM* |     9
 8     | Line Format Control**      | LNCTRL    | CHAR |     2
 9     | Grouping Code              | GROUP     | CHAR |     2
 10    | User Defined               | ACCT CODE | CHAR |    15

comp
Pays this invoice with a compliemntary payment. If there is an error, returns the error, otherwise returns false.
realtime_card
Attempts to pay this invoice with a credit card payment via a Business::OnlinePayment realtime gateway. See http://search.cpan.org/search?mode=module&query=Business%3A%3AOnlinePayment for supported processors.
realtime_ach
Attempts to pay this invoice with an electronic check (ACH) payment via a Business::OnlinePayment realtime gateway. See http://search.cpan.org/search?mode=module&query=Business%3A%3AOnlinePayment for supported processors.
realtime_lec
Attempts to pay this invoice with phone bill (LEC) payment via a Business::OnlinePayment realtime gateway. See http://search.cpan.org/search?mode=module&query=Business%3A%3AOnlinePayment for supported processors.
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.
print_text [ TIME [ , TEMPLATE ] ]
Returns an text invoice, as a list of lines.
TIME an optional value used to control the printing of overdue messages. The default is now. It isn't the date of the invoice; that's the `_date' field. It is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.
print_latex [ TIME [ , TEMPLATE ] ]
Internal method - returns a filename of a filled-in LaTeX template for this invoice (Note: add ".tex" to get the actual filename).
See print_ps and print_pdf for methods that return PostScript and PDF output.
TIME an optional value used to control the printing of overdue messages. The default is now. It isn't the date of the invoice; that's the `_date' field. It is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.
print_ps [ TIME [ , TEMPLATE ] ]
Returns an postscript invoice, as a scalar.
TIME an optional value used to control the printing of overdue messages. The default is now. It isn't the date of the invoice; that's the `_date' field. It is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.
print_pdf [ TIME [ , TEMPLATE ] ]
Returns an PDF invoice, as a scalar.
TIME an optional value used to control the printing of overdue messages. The default is now. It isn't the date of the invoice; that's the `_date' field. It is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.
print_html [ TIME [ , TEMPLATE [ , CID ] ] ]
Returns an HTML invoice, as a scalar.
TIME an optional value used to control the printing of overdue messages. The default is now. It isn't the date of the invoice; that's the `_date' field. It is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.
CID is a MIME Content-ID used to create a "cid:" URL for the logo image, used when emailing the invoice as part of a multipart/related MIME email.
invnum_date_pretty
Returns a string with the invoice number and date, for example: "Invoice #54 (3/20/2008)"
_date_pretty
Returns a string with the date, for example: "3/20/2008"

SUBROUTINES

process_reprint; process_reemail; process_refax; process_reftp; respool

CLASS METHODS

owed_sql
Returns an SQL fragment to retreive the amount owed (charged minus credited and paid).
net_sql
Returns an SQL fragment to retreive the net amount (charged minus credited).
paid_sql
Returns an SQL fragment to retreive the amount paid against this invoice.
credited_sql
Returns an SQL fragment to retreive the amount credited against this invoice.
search_sql HASHREF
Class method which returns an SQL WHERE fragment to search for parameters specified in HASHREF. Valid parameters are
begin
Epoch date (UNIX timestamp) setting a lower bound for _date values
end
Epoch date (UNIX timestamp) setting an upper bound for _date values
invnum_min
; invnum_max:; agentnum:; owed:; net:; days:; newest_percust
Note: validates all passed-in data; i.e. safe to use with unchecked CGI params.

BUGS

The delete method.

SEE ALSO

FS::Record, FS::cust_main, FS::cust_bill_pay, FS::cust_pay, FS::cust_bill_pkg, FS::cust_bill_credit, schema.html from the base documentation.

Retrieved from "http://freeside.biz/mediawiki/index.php?title=Freeside:1.7:Documentation:Developer/FS/cust_bill&oldid=5087"