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))
 
(5 intermediate revisions by the same user not shown)
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.
 +
; set_exemptions TAXOBJECT, OPTIONS
 +
:Sets up tax exemptions. TAXOBJECT is the [[Freeside:3:Documentation:Developer/FS/cust main county|FS::cust_main_county]] or [[Freeside:3:Documentation:Developer/FS/tax rate|FS::tax_rate]] record for the tax.
 +
 +
:This will deal with the following cases:
 +
:; Fully exempt customers (cust_main.tax flag) or customer classes (cust_class.tax).:; Customers exempt from specific named taxes (cust_main_exemption records).:; Taxes that don't apply to setup or recurring fees (cust_main_county.setuptax and recurtax, tax_rate.setuptax and recurtax).:; Packages that are marked as tax-exempt (part_pkg.setuptax, part_pkg.recurtax).:; Fees that aren't marked as taxable (part_fee.taxable).
 +
:It does NOT deal with monthly tax exemptions, which need more context than this humble little method cares to deal with.
 +
 +
:OPTIONS should include "custnum" => the customer number if this tax line hasn't been inserted (which it probably hasn't).
 +
 +
:Returns a list of exemption objects, which will also be attached to the line item as the 'cust_tax_exempt_pkg' pseudo-field. Inserting the line item will insert these records as well.
 +
; 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.
 +
; _item_discount
 +
:If this item has any discounts, returns a hashref in the format used by [[Freeside:3:Documentation:Developer/FS/Template Mixin# items cust bill pkg|" items cust bill pkg" in FS/Template Mixin|FS::Template_Mixin#_items_cust_bill_pkg|"_items_cust_bill_pkg" in FS::Template_Mixin]] to describe the discount(s) on an invoice. This will contain the keys 'description', 'amount', 'ext_description' (an arrayref of text lines describing the discounts), and '_is_discount' (a flag).
 +
 +
:The value for 'amount' will be negative, and will be scaled for the package quantity.
 +
; 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.
 +
 +
==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.

Latest revision as of 09:58, 10 April 2015

NAME

FS::cust_bill_pkg - Object methods for cust_bill_pkg records

SYNOPSIS

 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;

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 FS::cust_bill)
pkgnum
package (see 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 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 "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

METHODS

new HASHREF
Creates a new line item. To add the line item to the database, see "insert". Line items are normally created by calling the bill method of a customer object (see 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 FS::cust_bill_pkg_detail objects, if they aren't already.
set_exemptions TAXOBJECT, OPTIONS
Sets up tax exemptions. TAXOBJECT is the FS::cust_main_county or FS::tax_rate record for the tax.
This will deal with the following cases:
Fully exempt customers (cust_main.tax flag) or customer classes (cust_class.tax).
; Customers exempt from specific named taxes (cust_main_exemption records).:; Taxes that don't apply to setup or recurring fees (cust_main_county.setuptax and recurtax, tax_rate.setuptax and recurtax).:; Packages that are marked as tax-exempt (part_pkg.setuptax, part_pkg.recurtax).:; Fees that aren't marked as taxable (part_fee.taxable).
It does NOT deal with monthly tax exemptions, which need more context than this humble little method cares to deal with.
OPTIONS should include "custnum" => the customer number if this tax line hasn't been inserted (which it probably hasn't).
Returns a list of exemption objects, which will also be attached to the line item as the 'cust_tax_exempt_pkg' pseudo-field. Inserting the line item will insert these records as well.
cust_bill
Returns the invoice (see FS::cust_bill) for this invoice line item.
cust_main
Returns the customer (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 FS::cust_bill_pay_pkg and credit applications (see 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 FS::cust_bill_pay_pkg and credit applications (see FS::cust_credit_bill_pkg).
units
Returns the number of billing units (for tax purposes) represented by this, line item.
_item_discount
If this item has any discounts, returns a hashref in the format used by " items cust bill pkg" in FS/Template Mixin|FS::Template_Mixin#_items_cust_bill_pkg|"_items_cust_bill_pkg" in FS::Template_Mixin to describe the discount(s) on an invoice. This will contain the keys 'description', 'amount', 'ext_description' (an arrayref of text lines describing the discounts), and '_is_discount' (a flag).
The value for 'amount' will be negative, and will be scaled for the package quantity.
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 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.

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

FS::Record, FS::cust_bill, FS::cust_pkg, FS::cust_main, schema.html from the base documentation.