FS::cust_bill - Object methods for cust_bill records
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);
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
Deprecated fields
Specific use cases
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).
Adds this invoice to the database ("Posts" the invoice). If there is an error, returns the error, otherwise returns false.
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).
DO NOT USE THIS METHOD. Instead, apply a credit against the invoice, or use the void method.
This is only for internal use by void, which is what you should be using.
DO NOT USE THIS METHOD. Whatever reason you think you have is almost certainly wrong. Use void, that's what it is for. Really. This means you.
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.
Giant hack
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.
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 customer's last invoice before this one.
Returns the customer's invoice that follows this one
Returns a list consisting of the total previous balance for this customer, followed by the previous outstanding invoices (as FS::cust_bill objects also).
Whether to show the 'Previous Charges' section when printing this invoice. The negation of the 'disable_previous_balance' config setting.
Returns the line items (see FS::cust_bill_pkg) for this invoice.
Returns the line items (see FS::cust_bill_pkg) for this invoice and specified pkgnum.
Returns the packages (see FS::cust_pkg) corresponding to the line items for this invoice.
Returns true if any of the packages (or their definitions) corresponding to the line items for this invoice have the no_auto flag set.
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.
Returns the new-style customer billing events (see FS::cust_event) for this invoice.
Returns the number of new-style customer billing events (see FS::cust_event) for this invoice.
Returns the customer (see FS::cust_main) for this invoice.
Suspends all unsuspended packages (see FS::cust_pkg) for this invoice
Returns a list: an empty list on success or a list of errors.
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.
Cancel the packages on this invoice. Largely similar to the cust_main version, but does not bother yet with banned payment options
Returns all payment applications (see FS::cust_bill_pay) for this invoice.
Returns all applied credits (see FS::cust_credit_bill) for this invoice.
Returns all payment applications (see FS::cust_bill_pay) for this invoice applied against the matching pkgnum.
Returns all credit applications (see FS::cust_credit_bill) for this invoice applied against the matching pkgnum.
Returns all invoice batch records (FS::cust_bill_batch) for this invoice.
Returns all discount plans (FS::discount_plan) for this invoice, as a hash keyed by term length.
Returns the tax amount (see FS::cust_bill_pkg) for this invoice.
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).
Returns the amount to be displayed as the "Balance Due" on this invoice. Amount returned depends on conf flags for invoicing
See "owed" in FS::cust_bill for the true amount currently owed
Returns true if this invoice should be hidden. See the selfservice-hide_invoices-taxclass configuraiton setting.
Applies unapplied payments and credits to this invoice. Payments with the no_auto_apply flag set will not be applied.
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.
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.
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.
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)
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)
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)
Place this invoice into the open batch (see FS::bill_batch). If there isn't an open batch, one will be created.
HASHREF may contain any options to be passed to print_pdf.
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)
Sends this invoice data via FTP.
TEMPLATENAME is unused?
Spools this invoice data (see "spool_csv" in FS::cust_bill)
TEMPLATENAME is unused?
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.
Spools CSV invoice data.
Options are:
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
cust_bill or cust_bill_pkgrecord_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.
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.
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.
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.
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.
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.
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.
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).
Returns an array of hashrefs, each hashref representing a line-item on
the current bill for previous unpaid invoices.
keys for each previous_item:
- amount (see notes)
- pkgnum
- description
- invnum
- _date
Payments and credits shown on this invoice may vary based on configuraiton.
when conf flag previous_balance-payments_since is set:
This method works backwards to rebuild the invoice as a snapshot in time.
The invoice displayed will have the balances owed, and payments made,
reflecting the state of the account at the time of invoice generation.
Return sum of amounts from all items returned by _items_previous Results will vary based on invoicing conf flags
Return array of hashrefs containing credits to be shown as line-items
when rendering this bill.
keys for each credit item:
- crednum: id of payment
- amount: payment amount
- description: line item to be displayed on the bill
This method has three ways it selects which credits to display on
this bill:
1) Default Case: No Conf flag for 'previous_balance-payments_since'
Returns credits that have been applied to this bill only
2) Case:
Conf flag set for 'previous_balance-payments_since'
List all credits that have been recorded during the time period
between the timestamps of the last invoice and this invoice
3) Case:
Conf flag set for 'previous_balance-payments_since'
$opt{'template'} eq 'statement'
List all payments that have been recorded between the timestamps
of the previous invoice and the following invoice.
This is used to give the customer a receipt for a payment
in the form of their last bill with the payment amended.
I am concerned with this implementation, but leaving in place as is
If this option is selected, while viewing an older bill, the old bill
will show ALL future credits for future bills, but no charges for
future bills. Somebody could be misled into believing they have a
large account credit when they don't. Also, interrupts the chain of
invoices as an account history... the customer could have two invoices
in their fileing cabinet, for two different dates, both with a line item
for the same duplicate credit. The accounting is technically accurate,
but somebody could easily become confused and think two credits were
made, when really those two line items on two different bills represent
only a single credit
Return the total of al items from _items_credits Will vary based on invoice display conf flag
Returns an array of hashrefs for credits where - Credit issued after this invoice - Credit applied to an invoice before this invoice Returned hashrefs are of the format returned by _items_credits()
Returns an array of hashrefs for payments where - Payment occured after this invoice - Payment applied to an invoice before this invoice Returned hashrefs are of the format returned by _items_payments()
Return array of hashrefs containing payments to be shown as line-items
when rendering this bill.
keys for each payment item:
- paynum: id of payment
- amount: payment amount
- description: line item to be displayed on the bill
This method has three ways it selects which payments to display on
this bill:
1) Default Case: No Conf flag for 'previous_balance-payments_since'
Returns payments that have been applied to this bill only
2) Case:
Conf flag set for 'previous_balance-payments_since'
List all payments that have been recorded between the timestamps
of the previous invoice and this invoice
3) Case:
Conf flag set for 'previous_balance-payments_since'
$opt{'template'} eq 'statement'
List all payments that have been recorded between the timestamps
of the previous invoice and the following invoice.
I am concerned with this implementation, but leaving in place as is
If this option is selected, while viewing an older bill, the old bill
will show ALL future payments for future bills, but no charges for
future bills. Somebody could be misled into believing they have a
large account credit when they don't. Also, interrupts the chain of
invoices as an account history... the customer could have two invoices
in their fileing cabinet, for two different dates, both with a line item
for the same duplicate payment. The accounting is technically accurate,
but somebody could easily become confused and think two payments were
made, when really those two line items on two different bills represent
only a single payment.
Return a total of all records returned by _items_payments Results vary based on invoicing conf flags
Generate the line-items to be shown on the bill in the "Totals" section
Returns a list of hashrefs, each with the keys:
- total_item: description field
- total_amount: dollar-formatted number amount
Information presented by this method varies based on Conf
Conf previous_balance-payments_due
- default, flag not set
Only transactions that were applied to this bill bill be
displayed and calculated intothe total. If items exist in
the past-due section, those items will disappear from this
invoice if they have been paid off.
- previous_balance-payments_due flag is set
Transactions occuring after the timestsamp of this
invoice are not reflected on invoice line items
Only payments/credits applied between the previous invoice
and this one are displayed and calculated into the total
- previous_balance-payments_due && $opt{template} eq 'statement'
Same as above, except payments/credits occuring before the date
of the following invoice are also displayed and calculated into
the total
Conf previous_balance-exclude_from_total
- default, flag not set
The "Totals" section contains a single line item.
The dollar amount of this line items is a sum of old and new charges
- previous_balance-exclude_from_total flag is set
The "Totals" section contains two line items.
One for previous balance, one for new charges
!NOTE: Avent virtualization flag 'disable_previous_balance' can
override the global conf flag previous_balance-exclude_from_total
Conf invoice_show_prior_due_date
- default, flag not set
Total line item in the "Totals" section does not mention due date
- invoice_show_prior_due_date flag is set
Total line item in the "Totals" section includes either the due
date of the invoice, or the specified invoice terms
? Not sure why this is called "Prior" due date, since we seem to be
displaying THIS due date...
Returns an array of aged balance amounts from a given epoch timestamp.
The time of day is ignored for this calculation, so that slight differences
on the generation time of an invoice doesn't determine which column an
aged balance falls into.
Will not include any balances dated after the given timestamp in
the calculated totals
usage:
@aged_balances = $b->_items_aging_balances( $b->_date )
@aged_balances = (
under30d,
30d-60d,
60d-90d,
over90d
)
Returns true if this invoice has call details.
Returns an array of CSV strings representing the call details for this invoice The only option available is the boolean prepend_billed_number
Returns all FS::cust_pay_batch records linked to this invoice. Deprecated, will be removed.
Returns an SQL fragment to retreive the amount owed (charged minus credited and paid).
Returns an SQL fragment to retreive the net amount (charged minus credited).
Returns an SQL fragment to retreive the amount paid against this invoice.
Returns an SQL fragment to retreive the amount credited against this invoice.
Returns an SQL fragment to retrieve the due date of an invoice. Currently only supported on PostgreSQL.
The delete method.
FS::Record, FS::cust_main, FS::cust_bill_pay, FS::cust_pay, FS::cust_bill_pkg, FS::cust_credit, schema.html from the base documentation.
Hey! The above document had some coding errors, which are explained below:
Deleting unknown formatting code V<>