|
|
| Line 1: |
Line 1: |
| − | ==NAME==
| |
| − | FS::cust_bill_pkg - Object methods for cust_bill_pkg records
| |
| | | | |
| − | ==SYNOPSIS==
| |
| − | <code>
| |
| − | use FS::cust_bill_pkg;
| |
| − |
| |
| − | $record = new FS::cust_bill_pkg \%hash;
| |
| − | $record = new FS::cust_bill_pkg { 'column' => 'value' };
| |
| − |
| |
| − | $error = $record->insert;
| |
| − |
| |
| − | $error = $record->check;
| |
| − | </code>
| |
| − | ==DESCRIPTION==
| |
| − | An FS::cust_bill_pkg object represents an invoice line item. FS::cust_bill_pkg inherits from FS::Record. The following fields are currently supported:
| |
| − |
| |
| − | ; billpkgnum
| |
| − | :primary key
| |
| − | ; invnum
| |
| − | :invoice (see [[Freeside:3:Documentation:Developer/FS/cust bill|FS::cust_bill]])
| |
| − | ; pkgnum
| |
| − | :package (see [[Freeside:3:Documentation:Developer/FS/cust pkg|FS::cust_pkg]]) or 0 for the special virtual sales tax package, or -1 for the virtual line item (itemdesc is used for the line)
| |
| − | ; pkgpart_override
| |
| − | :optional package definition (see [[Freeside:3:Documentation:Developer/FS/part pkg|FS::part_pkg]]) override
| |
| − | ; setup
| |
| − | :setup fee
| |
| − | ; recur
| |
| − | :recurring fee
| |
| − | ; sdate
| |
| − | :starting date of recurring fee
| |
| − | ; edate
| |
| − | :ending date of recurring fee
| |
| − | ; itemdesc
| |
| − | :Line item description (overrides normal package description)
| |
| − | ; quantity
| |
| − | :If not set, defaults to 1
| |
| − | ; unitsetup
| |
| − | :If not set, defaults to setup
| |
| − | ; unitrecur
| |
| − | :If not set, defaults to recur
| |
| − | ; hidden
| |
| − | :If set to Y, indicates data should not appear as separate line item on invoice
| |
| − |
| |
| − | sdate and edate are specified as UNIX timestamps; 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.
| |
| − |
| |
| − | ==METHODS==
| |
| − | ; new HASHREF
| |
| − | :Creates a new line item. To add the line item to the database, see [[#insert|"insert"]]. Line items are normally created by calling the bill method of a customer object (see [[Freeside:3:Documentation:Developer/FS/cust main|FS::cust_main]]).
| |
| − | ; insert
| |
| − | :Adds this line item to the database. If there is an error, returns the error, otherwise returns false.
| |
| − | ; void
| |
| − | :Voids this line item: deletes the line item and adds a record of the voided line item to the FS::cust_bill_pkg_void table (and related tables).
| |
| − | ; delete
| |
| − | :Not recommended.
| |
| − | ; check
| |
| − | :Checks all fields to make sure this is a valid line item. If there is an error, returns the error, otherwise returns false. Called by the insert method.
| |
| − | ; regularize_details
| |
| − | :Converts the contents of the 'details' pseudo-field to [[Freeside:3:Documentation:Developer/FS/cust bill pkg detail|FS::cust_bill_pkg_detail]] objects, if they aren't already.
| |
| − | ; cust_bill
| |
| − | :Returns the invoice (see [[Freeside:3:Documentation:Developer/FS/cust bill|FS::cust_bill]]) for this invoice line item.
| |
| − | ; cust_main
| |
| − | :Returns the customer ([[Freeside:3:Documentation:Developer/FS/cust main|FS::cust_main]] object) for this line item.
| |
| − | ; previous_cust_bill_pkg
| |
| − | :Returns the previous cust_bill_pkg for this package, if any.
| |
| − | ; owed_setup
| |
| − | :Returns the amount owed (still outstanding) on this line item's setup fee, which is the amount of the line item minus all payment applications (see [[Freeside:3:Documentation:Developer/FS/cust bill pay pkg|FS::cust_bill_pay_pkg]] and credit applications (see [[Freeside:3:Documentation:Developer/FS/cust credit bill pkg|FS::cust_credit_bill_pkg]]).
| |
| − | ; owed_recur
| |
| − | :Returns the amount owed (still outstanding) on this line item's recurring fee, which is the amount of the line item minus all payment applications (see [[Freeside:3:Documentation:Developer/FS/cust bill pay pkg|FS::cust_bill_pay_pkg]] and credit applications (see [[Freeside:3:Documentation:Developer/FS/cust credit bill pkg|FS::cust_credit_bill_pkg]]).
| |
| − | ; units
| |
| − | :Returns the number of billing units (for tax purposes) represented by this, line item.
| |
| − | ; set_display OPTION => VALUE ...
| |
| − | :A helper method for ''insert'', populates the pseudo-field '''display''' with appropriate FS::cust_bill_pkg_display objects.
| |
| − |
| |
| − | :Options are passed as a list of name/value pairs. Options are:
| |
| − |
| |
| − | :part_pkg: FS::part_pkg object from this line item's package.
| |
| − |
| |
| − | :real_pkgpart: if this line item comes from a bundled package, the pkgpart of the owning package. Otherwise the same as the part_pkg's pkgpart above.
| |
| − | ; disintegrate
| |
| − | :Returns a hash: keys are "setup", "recur" or usage classnum, values are FS::cust_bill_pkg objects, each with no more than a single class (setup or recur) of charge.
| |
| − | ; usage CLASSNUM
| |
| − | :Returns the amount of the charge associated with usage class CLASSNUM if CLASSNUM is defined. Otherwise returns the total charge associated with usage.
| |
| − | ; usage_classes
| |
| − | :Returns a list of usage classnums associated with this invoice line's details.
| |
| − | ; cust_bill_pkg_fee
| |
| − | :Returns the list of associated cust_bill_pkg_fee objects, if this is a fee-type item.
| |
| − | ; cust_bill_pkg_tax_Xlocation
| |
| − | :Returns the list of associated cust_bill_pkg_tax_location and/or cust_bill_pkg_tax_rate_location objects
| |
| − | ; recur_show_zero; credited [ BEFORE, AFTER, OPTIONS ]
| |
| − | :Returns the sum of credits applied to this item. Arguments are the same as owed_sql/paid_sql/credited_sql.
| |
| − | ; tax_locationnum
| |
| − | :Returns the [[Freeside:3:Documentation:Developer/FS/cust location|FS::cust_location]] number that this line item is in for tax purposes. For package sales, it's the package tax location; for fees, it's the customer's default service location.
| |
| − | ; part_X
| |
| − | :Returns the [[Freeside:3:Documentation:Developer/FS/part pkg|FS::part_pkg]] or [[Freeside:3:Documentation:Developer/FS/part fee|FS::part_fee]] object that defines this charge. If called on a tax line, returns nothing.
| |
| − |
| |
| − | ==CLASS METHODS==
| |
| − | ; usage_sql
| |
| − | :Returns an SQL expression for the total usage charges in details on an item.
| |
| − | ; owed_sql [ BEFORE, AFTER, OPTIONS ]
| |
| − | :Returns an SQL expression for the amount owed. BEFORE and AFTER specify a date window. OPTIONS may include 'no_usage' (excludes usage charges) and 'setuprecur' (set to "setup" or "recur" to limit to one or the other).
| |
| − | ; paid_sql [ BEFORE, AFTER, OPTIONS ]
| |
| − | :Returns an SQL expression for the sum of payments applied to this item.
| |
| − |
| |
| − | ==BUGS==
| |
| − | setup and recur shouldn't be separate fields. There should be one "amount" field and a flag to tell you if it is a setup/one-time fee or a recurring fee.
| |
| − |
| |
| − | A line item with both should really be two separate records (preserving sdate and edate for setup fees for recurring packages - that information may be valuable later). Invoice generation (cust_main::bill), invoice printing (cust_bill), tax reports (report_tax.cgi) and line item reports (cust_bill_pkg.cgi) would need to be updated.
| |
| − |
| |
| − | owed_setup and owed_recur could then be repaced by just owed, and cust_bill::open_cust_bill_pkg and cust_bill_ApplicationCommon::apply_to_lineitems could be simplified.
| |
| − |
| |
| − | The upgrade procedure is pretty sketchy.
| |
| − |
| |
| − | ==SEE ALSO==
| |
| − | [[Freeside:3:Documentation:Developer/FS/Record|FS::Record]], [[Freeside:3:Documentation:Developer/FS/cust bill|FS::cust_bill]], [[Freeside:3:Documentation:Developer/FS/cust pkg|FS::cust_pkg]], [[Freeside:3:Documentation:Developer/FS/cust main|FS::cust_main]], schema.html from the base documentation.
| |
