Difference between revisions of "Freeside:3:Documentation:Developer/FS/cust bill"

From Freeside
Jump to: navigation, search
m (Edit via perl MediaWiki framework (1.13))
 
m (Edit via perl MediaWiki framework (1.13))
Line 28: Line 28:
 
   
 
   
 
   @lines = $cust_bill->print_text;
 
   @lines = $cust_bill->print_text;
   @lines = $cust_bill->print_text $time;
+
   @lines = $cust_bill->print_text('time' => $time);
 
</code>
 
</code>
 
==DESCRIPTION==
 
==DESCRIPTION==
Line 38: Line 38:
 
Customer info at invoice generation time
 
Customer info at invoice generation time
  
; previous_balance; billing_balance
+
; billing_balance - the customer's balance at the time the invoice was generated (not including charges on this invoice); previous_balance - the billing_balance of this customer's previous invoice plus the charges on that invoice
 
Deprecated
 
Deprecated
  
Line 50: Line 50:
 
; insert
 
; insert
 
:Adds this invoice to the database ("Posts" the invoice). If there is an error, returns the error, otherwise returns false.
 
:Adds this invoice to the database ("Posts" the invoice). If there is an error, returns the error, otherwise returns false.
 +
; void
 +
:Voids this invoice: deletes the invoice and adds a record of the voided invoice to the FS::cust_bill_void table (and related tables starting from FS::cust_bill_pkg_void).
 
; delete
 
; delete
:This method now works but you probably shouldn't use it. Instead, apply a credit against the invoice.
+
:This method now works but you probably shouldn't use it. Instead, apply a credit against the invoice, or use the new void method.
  
 
: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.
 
: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.
Line 66: Line 68:
 
; display_invnum
 
; display_invnum
 
:Returns the displayed invoice number for this invoice: agent_invid if cust_bill-default_agent_invid is set and it has a value, invnum otherwise.
 
:Returns the displayed invoice number for this invoice: agent_invid if cust_bill-default_agent_invid is set and it has a value, invnum otherwise.
 +
; previous_bill
 +
:Returns the customer's last invoice before this one.
 
; previous
 
; 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).
 
:Returns a list consisting of the total previous balance for this customer, followed by the previous outstanding invoices (as FS::cust_bill objects also).
 +
; enable_previous
 +
:Whether to show the 'Previous Charges' section when printing this invoice. The negation of the 'disable_previous_balance' config setting.
 
; cust_bill_pkg
 
; cust_bill_pkg
 
:Returns the line items (see [[Freeside:3:Documentation:Developer/FS/cust bill pkg|FS::cust_bill_pkg]]) for this invoice.
 
:Returns the line items (see [[Freeside:3:Documentation:Developer/FS/cust bill pkg|FS::cust_bill_pkg]]) for this invoice.
Line 133: Line 139:
 
:; from
 
:; from
 
::sender address, required
 
::sender address, required
:; tempate
+
:; template
 
::alternate template name, optional
 
::alternate template name, optional
 
:; print_text
 
:; print_text
Line 145: Line 151:
 
; mimebuild_pdf
 
; mimebuild_pdf
 
:Returns a list suitable for passing to MIME::Entity->build(), representing this invoice as PDF attachment.
 
:Returns a list suitable for passing to MIME::Entity->build(), representing this invoice as PDF attachment.
; send HASHREF | [ TEMPLATE [ , AGENTNUM [ , INVOICE_FROM [ , AMOUNT ] ] ] ]
+
; send HASHREF
 
:Sends this invoice to the destinations configured for this customer: sends email, prints and/or faxes. See [[Freeside:3:Documentation:Developer/FS/cust main invoice|FS::cust_main_invoice]].
 
:Sends this invoice to the destinations configured for this customer: sends email, prints and/or faxes. See [[Freeside:3:Documentation:Developer/FS/cust main invoice|FS::cust_main_invoice]].
  
:Options can be passed as a hashref (recommended) or as a list of up to four values for templatename, agentnum, invoice_from and amount.
+
:Options can be passed as a hashref. Positional parameters are no longer allowed.
  
:''template'', if specified, is the name of a suffix for alternate invoices.
+
:''template'': a suffix for alternate invoices
 +
 
 +
:''agentnum'': obsolete, now does nothing.
  
:''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'' overrides the default email invoice From: address.
  
:''invoice_from'', if specified, overrides the default email invoice From: address.
+
:''amount'': obsolete, does nothing
  
:''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.
+
:''notice_name'' overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required).
  
:''notice_name'', if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
+
:''lpr'' overrides the system 'lpr' option as the command to print a document from standard input.
 
; email HASHREF | [ TEMPLATE [ , INVOICE_FROM ] ]
 
; email HASHREF | [ TEMPLATE [ , INVOICE_FROM ] ]
:Emails this invoice.
+
:Sends this invoice to the customer's email destination(s).
  
:Options can be passed as a hashref (recommended) or as a list of up to two values for templatename and invoice_from.
+
:Options must be passed as a hashref. Positional parameters are no longer allowed.
  
 
:''template'', if specified, is the name of a suffix for alternate invoices.
 
:''template'', if specified, is the name of a suffix for alternate invoices.
Line 168: Line 176:
 
:''invoice_from'', if specified, overrides the default email invoice From: address.
 
:''invoice_from'', if specified, overrides the default email invoice From: address.
  
:''notice_name'', if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
+
:''notice_name'' is the name of the sent document.
; lpr_data HASHREF | [ TEMPLATE ]
+
; lpr_data HASHREF
 
:Returns the postscript or plaintext for this invoice as an arrayref.
 
:Returns the postscript or plaintext for this invoice as an arrayref.
  
:Options can be passed as a hashref (recommended) or as a single optional value for template.
+
:Options must be passed as a hashref. Positional parameters are no longer allowed.
  
 
:''template'', if specified, is the name of a suffix for alternate invoices.
 
:''template'', if specified, is the name of a suffix for alternate invoices.
  
 
:''notice_name'', if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
 
:''notice_name'', if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
; print HASHREF | [ TEMPLATE ]
+
; print HASHREF
 
:Prints this invoice.
 
:Prints this invoice.
  
:Options can be passed as a hashref (recommended) or as a single optional value for template.
+
:Options must be passed as a hashref.
  
 
:''template'', if specified, is the name of a suffix for alternate invoices.
 
:''template'', if specified, is the name of a suffix for alternate invoices.
  
 
:''notice_name'', if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
 
:''notice_name'', if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
; fax_invoice HASHREF | [ TEMPLATE ]
+
; fax_invoice HASHREF
 
:Faxes this invoice.
 
:Faxes this invoice.
  
:Options can be passed as a hashref (recommended) or as a single optional value for template.
+
:Options must be passed as a hashref.
  
 
:''template'', if specified, is the name of a suffix for alternate invoices.
 
:''template'', if specified, is the name of a suffix for alternate invoices.
Line 205: Line 213:
  
 
:TEMPLATENAME is unused?
 
: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, ...
 
; send_csv OPTION => VALUE, ...
 
:Sends invoice as a CSV data-file to a remote host with the specified protocol.
 
:Sends invoice as a CSV data-file to a remote host with the specified protocol.
Line 221: Line 227:
  
 
:Options are:
 
:Options are:
:; format - any of FS&#58;&#58;Misc&#58;&#58;&#58;&#58;Invoicing&#58;&#58;spool_formats:; dest - if set (to POST, EMAIL or FAX), only sends spools invoices if the customer has the corresponding invoice destinations set (see [[Freeside:3:Documentation:Developer/FS/cust main invoice|FS::cust_main_invoice]]).:; agent_spools - if set to a true value, will spool to per-agent files rather than a single global file:; ftp_targetnum - if set to an FTP target (see [[Freeside:3:Documentation:Developer/FS/ftp target|FS::ftp_target]]), will append to that spool. [[Freeside:3:Documentation:Developer/FS/Cron/upload|FS::Cron::upload]] will then send the spool file to that destination.:; 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, ...
+
:; format - any of FS&#58;&#58;Misc&#58;&#58;&#58;&#58;Invoicing&#58;&#58;spool_formats:; dest - if set (to POST, EMAIL or FAX), only sends spools invoices if the customer has the corresponding invoice destinations set (see [[Freeside:3:Documentation:Developer/FS/cust main invoice|FS::cust_main_invoice]]).:; agent_spools - if set to a true value, will spool to per-agent files rather than a single global file:; upload_targetnum - if set to a target (see [[Freeside:3:Documentation:Developer/FS/upload target|FS::upload_target]]), will append to that spool. [[Freeside:3:Documentation:Developer/FS/Cron/upload|FS::Cron::upload]] will then send the spool file to that destination.:; 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.:; time - the "current time". Controls the printing of past due messages in the ICS format.; print_csv OPTION => VALUE, ...
 
:Returns CSV data for this invoice.
 
:Returns CSV data for this invoice.
  
Line 295: Line 301:
 
:If format is 'oneline', there is no detail file. Each invoice has a header line only, with the fields:
 
:If format is 'oneline', there is no detail file. Each invoice has a header line only, with the fields:
  
:Agent number, agent name, customer number, first name, last name, address line 1, address line 2, city, state, zip, invoice date, invoice number, amount charged, amount due,
+
:Agent number, agent name, customer number, first name, last name, address line 1, address line 2, city, state, zip, invoice date, invoice number, amount charged, amount due, previous balance, due date.
  
 
:and then, for each line item, three columns containing the package number, description, and amount.
 
:and then, for each line item, three columns containing the package number, description, and amount.
Line 314: Line 320:
 
; batch_card OPTION => VALUE...
 
; batch_card OPTION => VALUE...
 
:Adds a payment for this invoice to the pending credit card batch (see [[Freeside:3: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.
 
:Adds a payment for this invoice to the pending credit card batch (see [[Freeside:3: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.
; print_text HASHREF | [ TIME [ , TEMPLATE [ , OPTION => VALUE ... ] ] ]
 
:Returns an text invoice, as a list of lines.
 
 
:Options can be passed as a hashref (recommended) or as a list of time, template and then any key/value pairs for any other options.
 
 
:''time'', if specified, is 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 [[perlfunc#time|"time" in perlfunc]]. Also see [[Freeside:3:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:3:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
 
 
:''template'', if specified, is the name of a suffix for alternate invoices.
 
 
:''notice_name'', if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
 
; print_latex HASHREF | [ TIME [ , TEMPLATE [ , OPTION => VALUE ... ] ] ]
 
:Internal method - returns a filename of a filled-in LaTeX template for this invoice (Note: add ".tex" to get the actual filename), and a filename of an associated logo (with the .eps extension included).
 
 
:See print_ps and print_pdf for methods that return PostScript and PDF output.
 
 
:Options can be passed as a hashref (recommended) or as a list of time, template and then any key/value pairs for any other options.
 
 
:''time'', if specified, is 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 [[perlfunc#time|"time" in perlfunc]]. Also see [[Freeside:3:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:3:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
 
 
:''template'', if specified, is the name of a suffix for alternate invoices.
 
 
:''notice_name'', if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
 
 
; invoice_barcode DIR_OR_FALSE
 
; invoice_barcode DIR_OR_FALSE
 
:Generates an invoice barcode PNG. If DIR_OR_FALSE is a true value, it is taken as the temp directory where the PNG file will be generated and the PNG file name is returned. Otherwise, the PNG image itself is returned.
 
:Generates an invoice barcode PNG. If DIR_OR_FALSE is a true value, it is taken as the temp directory where the PNG file will be generated and the PNG file name is returned. Otherwise, the PNG image itself is returned.
; print_generic OPTION => VALUE ...
 
:Internal method - returns a filled-in template for this invoice as a scalar.
 
 
:See print_ps and print_pdf for methods that return PostScript and PDF output.
 
 
:Non optional options include format - latex, html, template
 
 
:Optional options include
 
 
:template - a value used as a suffix for a configuration template
 
 
:time - a 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 [[perlfunc#time|"time" in perlfunc]]. Also see [[Freeside:3:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:3:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
 
 
:cid -
 
 
:unsquelch_cdr - overrides any per customer cdr squelching when true
 
 
:notice_name - overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
 
 
:locale - override customer's locale
 
; print_ps HASHREF | [ TIME [ , TEMPLATE ] ]
 
:Returns an postscript invoice, as a scalar.
 
 
:Options can be passed as a hashref (recommended) or as a list of time, template and then any key/value pairs for any other options.
 
 
:''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 [[perlfunc#time|"time" in perlfunc]]. Also see [[Freeside:3:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:3:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
 
 
:''notice_name'', if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
 
; print_pdf HASHREF | [ TIME [ , TEMPLATE ] ]
 
:Returns an PDF invoice, as a scalar.
 
 
:Options can be passed as a hashref (recommended) or as a list of time, template and then any key/value pairs for any other options.
 
 
:''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 [[perlfunc#time|"time" in perlfunc]]. Also see [[Freeside:3:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:3:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
 
 
:''template'', if specified, is the name of a suffix for alternate invoices.
 
 
:''notice_name'', if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
 
; print_html HASHREF | [ 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 [[perlfunc#time|"time" in perlfunc]]. Also see [[Freeside:3:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:3:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
 
 
:''template'', if specified, is the name of a suffix for alternate invoices.
 
 
:''notice_name'', if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
 
 
:''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
 
; invnum_date_pretty
:Returns a string with the invoice number and date, for example: "Invoice #54 (3/20/2008)"
+
: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"
 
; _items_sections LATE SUMMARYPAGE ESCAPE EXTRA_SECTIONS FORMAT
 
:Generate section information for all items appearing on this invoice. This will only be called for multi-section invoices.
 
 
 
:For each line item ([[Freeside:3:Documentation:Developer/FS/cust bill pkg|FS::cust_bill_pkg]] record), this will fetch all related display records ([[Freeside:3:Documentation:Developer/FS/cust bill pkg display|FS::cust_bill_pkg_display]]) and organize them into two groups ("early" and "late" according to whether they come before or after the total), then into sections. A subtotal is calculated for each section.
 
 
 
:Section descriptions are returned in sort weight order. Each consists of a hash containing:
 
 
 
:description: the package category name, escaped subtotal: the total charges in that section tax_section: a flag indicating that the section contains only tax charges summarized: same as tax_section, for some reason sort_weight: the package category's sort weight
 
 
 
:If 'condense' is set on the display record, it also contains everything returned from <tt>_condense_section()</tt>, i.e. <tt>_condensed_foo_generator</tt> coderefs to generate parts of the invoice. This is not advised.
 
 
 
:Arguments:
 
 
 
:LATE: an arrayref to push the "late" section hashes onto. The "early" group is simply returned from the method.
 
 
 
:SUMMARYPAGE: a flag indicating whether this is a summary-format invoice. Turning this on has the following effects: - Ignores display items with the 'summary' flag. - Combines all items into the "early" group. - Creates sections for all non-disabled package categories, even if they have no charges on this invoice, as well as a section with no name.
 
 
 
:ESCAPE: an escape function to use for section titles.
 
 
 
:EXTRA_SECTIONS: an arrayref of additional sections to return after the sorted list. If there are any of these, section subtotals exclude usage charges.
 
 
 
:FORMAT: 'latex', 'html', or 'template' (i.e. text). Not used, but passed through to <tt>_condense_section()</tt>.
 
; total_line_generator FORMAT
 
:Returns a coderef used for generation of invoice total line items for this usage_class. FORMAT is either html or latex
 
; _items_pkg [ OPTIONS ]
 
:Return line item hashes for each package item on this invoice. Nearly equivalent to
 
 
 
:$self->_items_cust_bill_pkg([ $self->cust_bill_pkg ])
 
 
 
:The only OPTIONS accepted is 'section', which may point to a hashref with a key named 'condensed', which may have a true value. If it does, this method tries to merge identical items into items with 'quantity' equal to the number of items (not the sum of their separate quantities, for some reason).
 
; _items_cust_bill_pkg CUST_BILL_PKGS OPTIONS
 
:Takes an arrayref of [[Freeside:3:Documentation:Developer/FS/cust bill pkg|FS::cust_bill_pkg]] objects, and returns a list of hashrefs describing the line items they generate on the invoice.
 
 
 
:OPTIONS may include:
 
 
 
:format: the invoice format.
 
 
 
:escape_function: the function used to escape strings.
 
 
 
:DEPRECATED? (expensive, mostly unused?) format_function: the function used to format CDRs.
 
 
 
:section: a hashref containing 'description'; if this is present, cust_bill_pkg_display records not belonging to this section are ignored.
 
 
 
:multisection: a flag indicating that this is a multisection invoice, which does something complicated.
 
  
:multilocation: a flag to display the location label for the package.
+
:Intended for back-end context, with regard to translation and date formatting.
  
:Returns a list of hashrefs, each of which may contain:
+
:Returns a list of detail items summarizing the usage charges on this invoice. Each one will have 'amount', 'description' (the usage charge name), and 'usage_classnum'.
  
:pkgnum, description, amount, unit_amount, quantity, _is_setup, and ext_description, which is an arrayref of detail lines to show below the package line.
+
:OPTIONS can include 'escape' (a function to escape the descriptions).
; _items_discounts_avail
 
:Returns an array of line item hashrefs representing available term discounts for this invoice. This makes the same assumptions that apply to term discounts in general: that the package is billed monthly, at a flat rate, with no usage charges. A prorated first month will be handled, as will a setup fee if the discount is allowed to apply to setup fees.
 
 
; call_details [ OPTION => VALUE ... ]
 
; call_details [ OPTION => VALUE ... ]
 
:Returns an array of CSV strings representing the call details for this invoice The only option available is the boolean prepend_billed_number
 
:Returns an array of CSV strings representing the call details for this invoice The only option available is the boolean prepend_billed_number
Line 470: Line 358:
 
:; net
 
:; net
 
::flag, return net invoices only
 
::flag, return net invoices only
:; days:; newest_percust
+
:; days:; newest_percust:; custnum
 +
::Return only invoices belonging to that customer.
 +
:; cust_classnum
 +
::Limit to that customer class (single value or arrayref).
 +
:; payby
 +
::Limit to customers with that payment method (single value or arrayref).
 +
:; refnum
 +
::Limit to customers with that advertising source.
 +
 
 
:Note: validates all passed-in data; i.e. safe to use with unchecked CGI params.
 
:Note: validates all passed-in data; i.e. safe to use with unchecked CGI params.
  
Line 478: Line 374:
 
==SEE ALSO==
 
==SEE ALSO==
 
[[Freeside:3:Documentation:Developer/FS/Record|FS::Record]], [[Freeside:3:Documentation:Developer/FS/cust main|FS::cust_main]], [[Freeside:3:Documentation:Developer/FS/cust bill pay|FS::cust_bill_pay]], [[Freeside:3:Documentation:Developer/FS/cust pay|FS::cust_pay]], [[Freeside:3:Documentation:Developer/FS/cust bill pkg|FS::cust_bill_pkg]], [[Freeside:3:Documentation:Developer/FS/cust bill credit|FS::cust_bill_credit]], schema.html from the base documentation.
 
[[Freeside:3:Documentation:Developer/FS/Record|FS::Record]], [[Freeside:3:Documentation:Developer/FS/cust main|FS::cust_main]], [[Freeside:3:Documentation:Developer/FS/cust bill pay|FS::cust_bill_pay]], [[Freeside:3:Documentation:Developer/FS/cust pay|FS::cust_pay]], [[Freeside:3:Documentation:Developer/FS/cust bill pkg|FS::cust_bill_pkg]], [[Freeside:3:Documentation:Developer/FS/cust bill credit|FS::cust_bill_credit]], schema.html from the base documentation.
 +
 +
==POD ERRORS==
 +
Hey! '''The above document had some coding errors, which are explained below:'''
 +
 +
; Around line 2982&#58;
 +
:Unknown directive: =sub

Revision as of 13:32, 27 June 2014

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' => $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:

Regular fields

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; invoice_terms - optional terms override for this specific invoice

Customer info at invoice generation time

billing_balance - the customer's balance at the time the invoice was generated (not including charges on this invoice); previous_balance - the billing_balance of this customer's previous invoice plus the charges on that invoice

Deprecated

printed - deprecated

Specific use cases

closed - books closed flag, empty or `Y'; statementnum - invoice aggregation (see FS::cust_statement); agent_invid - legacy invoice number; promised_date - customer promised payment date, for collection

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.
void
Voids this invoice: deletes the invoice and adds a record of the voided invoice to the FS::cust_bill_void table (and related tables starting from FS::cust_bill_pkg_void).
delete
This method now works but you probably shouldn't use it. Instead, apply a credit against the invoice, or use the new void method.
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 ]
You can, but probably shouldn't modify invoices...
Replaces the OLD_RECORD with this one in the database, or, if OLD_RECORD is not supplied, replaces this record. If there is an error, returns the error, otherwise returns false.
add_cc_surcharge
Giant hack
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.
display_invnum
Returns the displayed invoice number for this invoice: agent_invid if cust_bill-default_agent_invid is set and it has a value, invnum otherwise.
previous_bill
Returns the customer's last invoice before this one.
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).
enable_previous
Whether to show the 'Previous Charges' section when printing this invoice. The negation of the 'disable_previous_balance' config setting.
cust_bill_pkg
Returns the line items (see FS::cust_bill_pkg) for this invoice.
cust_bill_pkg_pkgnum PKGNUM
Returns the line items (see FS::cust_bill_pkg) for this invoice and specified pkgnum.
cust_pkg
Returns the packages (see FS::cust_pkg) corresponding to the line items for this invoice.
no_auto
Returns true if any of the packages (or their definitions) corresponding to the line items for this invoice have the no_auto flag set.
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 (deprecated, old-style events - see FS::cust_bill_event) for this invoice.
num_cust_bill_event
Returns the number of completed invoice events (deprecated, old-style events - see FS::cust_bill_event) for this invoice.
cust_event
Returns the new-style customer billing events (see FS::cust_event) for this invoice.
num_cust_event
Returns the number of new-style customer billing events (see FS::cust_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; cust_credit_bill
Returns all applied credits (see FS::cust_credit_bill) for this invoice.
cust_bill_pay_pkg PKGNUM
Returns all payment applications (see FS::cust_bill_pay) for this invoice applied against the matching pkgnum.
cust_credit_bill_pkg PKGNUM
Returns all credit applications (see FS::cust_credit_bill) for this invoice applied against the matching pkgnum.
cust_bill_batch
Returns all invoice batch records (FS::cust_bill_batch) for this invoice.
discount_plans
Returns all discount plans (FS::discount_plan) for this invoice, as a hash keyed by term length.
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).
hide
Returns true if this invoice should be hidden. See the selfservice-hide_invoices-taxclass configuraiton setting.
apply_payments_and_credits [ OPTION => VALUE ... ]
Applies unapplied payments and credits to this invoice.
A hash of optional arguments may be passed. Currently "manual" is supported. If true, a payment receipt is sent instead of a statement when 'payment_receipt_email' configuration option is set.
If there is an error, returns the error, otherwise returns false.
generate_email OPTION => VALUE ...
Options:
from
sender address, required
template
alternate template name, optional
print_text
text attachment arrayref, optional
subject
email subject, optional
notice_name
notice name instead of "Invoice", 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 HASHREF
Sends this invoice to the destinations configured for this customer: sends email, prints and/or faxes. See FS::cust_main_invoice.
Options can be passed as a hashref. Positional parameters are no longer allowed.
template: a suffix for alternate invoices
agentnum: obsolete, now does nothing.
invoice_from overrides the default email invoice From: address.
amount: obsolete, does nothing
notice_name overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required).
lpr overrides the system 'lpr' option as the command to print a document from standard input.
email HASHREF | [ TEMPLATE [ , INVOICE_FROM ] ]
Sends this invoice to the customer's email destination(s).
Options must be passed as a hashref. Positional parameters are no longer allowed.
template, if specified, is the name of a suffix for alternate invoices.
invoice_from, if specified, overrides the default email invoice From: address.
notice_name is the name of the sent document.
lpr_data HASHREF
Returns the postscript or plaintext for this invoice as an arrayref.
Options must be passed as a hashref. Positional parameters are no longer allowed.
template, if specified, is the name of a suffix for alternate invoices.
notice_name, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
print HASHREF
Prints this invoice.
Options must be passed as a hashref.
template, if specified, is the name of a suffix for alternate invoices.
notice_name, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
fax_invoice HASHREF
Faxes this invoice.
Options must be passed as a hashref.
template, if specified, is the name of a suffix for alternate invoices.
notice_name, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
batch_invoice [ HASHREF ]
Place this invoice into the open batch (see FS::bill_batch). If there isn't an open batch, one will be created.
get_open_batch
Returns the currently open batch as an FS::bill_batch object, creating a new one if necessary. (A per-agent batch if invoice_print_pdf-spoolagent is enabled)
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_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 - any of FS::Misc::::Invoicing::spool_formats
; 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:; upload_targetnum - if set to a target (see FS::upload_target), will append to that spool. FS::Cron::upload will then send the spool file to that destination.:; 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.:; time - the "current time". Controls the printing of past due messages in the ICS format.; print_csv OPTION => VALUE, ...
Returns CSV data for this invoice.
Options are:
format - 'default', 'billco', 'oneline', 'bridgestone'
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

If format is 'oneline', there is no detail file. Each invoice has a header line only, with the fields:
Agent number, agent name, customer number, first name, last name, address line 1, address line 2, city, state, zip, invoice date, invoice number, amount charged, amount due, previous balance, due date.
and then, for each line item, three columns containing the package number, description, and amount.
If format is 'bridgestone', there is no detail file. Each invoice has a header line with the following fields in a fixed-width format:
Customer number (in display format), date, name (first last), company, address 1, address 2, city, state, zip.
This is a mailing list format, and has no per-invoice fields. To avoid sending redundant notices, the spooling event should have a "once" or "once_percust_every" condition.
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.
invoice_barcode DIR_OR_FALSE
Generates an invoice barcode PNG. If DIR_OR_FALSE is a true value, it is taken as the temp directory where the PNG file will be generated and the PNG file name is returned. Otherwise, the PNG image itself is returned.
invnum_date_pretty
Returns a string with the invoice number and date, for example: "Invoice #54 (3/20/2008)".
Intended for back-end context, with regard to translation and date formatting.
Returns a list of detail items summarizing the usage charges on this invoice. Each one will have 'amount', 'description' (the usage charge name), and 'usage_classnum'.
OPTIONS can include 'escape' (a function to escape the descriptions).
call_details [ OPTION => VALUE ... ]
Returns an array of CSV strings representing the call details for this invoice The only option available is the boolean prepend_billed_number

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.
due_date_sql
Returns an SQL fragment to retrieve the due date of an invoice. Currently only supported on PostgreSQL.
search_sql_where HASHREF
Class method which returns an SQL WHERE fragment to search for parameters specified in HASHREF. Valid parameters are
_date
List reference of start date, end date, as UNIX timestamps.
invnum_min
; invnum_max:; agentnum:; charged
List reference of charged limits (exclusive).
owed
List reference of charged limits (exclusive).
open
flag, return open invoices only
net
flag, return net invoices only
days
; newest_percust:; custnum
Return only invoices belonging to that customer.
cust_classnum
Limit to that customer class (single value or arrayref).
payby
Limit to customers with that payment method (single value or arrayref).
refnum
Limit to customers with that advertising source.
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.

POD ERRORS

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

Around line 2982:
Unknown directive: =sub