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

Revision as of 20:03, 27 June 2012

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.

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.

cust_pkg

Returns the package (see FS::cust_pkg) for this invoice line item.

part_pkg

Returns the package definition for this invoice line item.

cust_bill

Returns the invoice (see FS::cust_bill) for this invoice line item.

previous_cust_bill_pkg

Returns the previous cust_bill_pkg for this package, if any.

details [ OPTION => VALUE ... ]

Returns an array of detail information for the invoice line item.

Currently available options are: format, escape_function and format_function.

If format is set to html or latex then the array members are improved for tabular appearance in those environments if possible.

If escape_function is set then the array members are processed by this function before being returned.

format_function overrides the normal HTML or LaTeX function for returning formatted CDRs. It can be set to a subroutine which returns an empty list to skip usage detail:

 'format_function' => sub { () },

details_header [ OPTION => VALUE ... ]

Returns a list representing an invoice line item detail header, if any. This relies on the behavior of voip_cdr in that it expects the header to be the first CSV formatted detail (as is expected by invoice generation routines). Returns the empty list otherwise.

desc

Returns a description for this line item. For typical line items, this is the pkg field of the corresponding FS::part_pkg object (see FS::part_pkg). For one-shot line items and named taxes, it is the itemdesc field of this line item, and for generic taxes, simply returns "Tax".

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.

quantity; unitsetup; unitrecur; 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 the

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 list of cust_bill_pkg objects each with no more than a single class (including 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_display [ type => TYPE ]

Returns an array of display information for the invoice line item optionally limited to 'TYPE'.

cust_bill_pkg_tax_Xlocation

Returns the list of associated cust_bill_pkg_tax_location and/or cust_bill_pkg_tax_rate_location objects

cust_bill_pkg_detail [ CLASSNUM ]

Returns the list of associated cust_bill_pkg_detail objects The optional CLASSNUM argument will limit the details to the specified usage class.

cust_bill_pkg_discount

Returns the list of associated cust_bill_pkg_discount objects.

recur_show_zero

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.

SEE ALSO

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