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

From Freeside
Jump to: navigation, search
m (Edit via perl MediaWiki framework (1.13))
m (Edit via perl MediaWiki framework (1.13))
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.
 

Revision as of 05:26, 10 February 2015