Freeside:3:Documentation:Developer/FS/cust main/Billing

NAME

FS::cust_main::Billing - Billing mixin for cust_main

DESCRIPTION

These methods are available on FS::cust_main objects.

METHODS

bill_and_collect

Cancels and suspends any packages due, generates bills, applies payments and credits, and applies collection events to run cards, send bills and notices, etc.

By default, warns on errors and continues with the next operation (but see the "fatal" flag below).

Options are passed as name-value pairs. Currently available options are:

time

Bills the customer as if it were that time. Specified as a UNIX timestamp; see "time" in perlfunc). Also see Time::Local and Date::Parse for conversion functions. For example:

use Date::Parse;
...
$cust_main->bill( 'time' => str2time('April 20th, 2001') );

invoice_time

Used in conjunction with the time option, this option specifies the date of for the generated invoices. Other calculations, such as whether or not to generate the invoice in the first place, are not affected.

check_freq

"1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq)

resetup

If set true, re-charges setup fees.

fatal

If set any errors prevent subsequent operations from continusing. If set specifically to "return", returns the error (or false, if there is no error). Any other true value causes errors to die.

debug

Debugging level. Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)

job

Optional FS::queue entry to receive status updates.

Options are passed to the bill and collect methods verbatim, so all options of those methods are also available.

bill OPTIONS

Generates invoices (see FS::cust_bill) for this customer. Usually used in conjunction with the collect method by calling bill_and_collect.

If there is an error, returns the error, otherwise returns false.

Options are passed as name-value pairs. Currently available options are:

resetup

If set true, re-charges setup fees.

recurring_only

If set true then only bill recurring charges, not setup, usage, one time charges, etc.

freq_override

If set, then override the normal frequency and look for a part_pkg_discount to take at that frequency. This is appropriate only when the normal frequency for all packages is monthly, and is an error otherwise. Use pkg_list to limit the set of packages included in billing.

time

Bills the customer as if it were that time. Specified as a UNIX timestamp; see "time" in perlfunc). Also see Time::Local and Date::Parse for conversion functions. For example:

use Date::Parse;
...
$cust_main->bill( 'time' => str2time('April 20th, 2001') );

pkg_list

An array ref of specific packages (objects) to attempt billing, instead trying all of them.

$cust_main->bill( pkg_list => [$pkg1, $pkg2] );

not_pkgpart

A hashref of pkgparts to exclude from this billing run (can also be specified as a comma-separated scalar).

no_prepaid

Do not bill prepaid packages. Used by freeside-daily.

invoice_time

Used in conjunction with the time option, this option specifies the date of for the generated invoices. Other calculations, such as whether or not to generate the invoice in the first place, are not affected.

cancel

This boolean value informs the us that the package is being cancelled. This typically might mean not charging the normal recurring fee but only usage fees since the last billing. Setup charges may be charged. Not all package plans support this feature (they tend to charge 0).

no_usage_reset

Prevent the resetting of usage limits during this call.

no_commit

Do not save the generated bill in the database. Useful with return_bill

return_bill

A list reference on which the generated bill(s) will be returned.

invoice_terms

Optional terms to be printed on this invoice. Otherwise, customer-specific terms or the default terms are used.

calculate_taxes LINEITEMREF TAXHASHREF INVOICE_TIME

Generates tax line items (see FS::cust_bill_pkg) for this customer. Usually used internally by bill method bill.

If there is an error, returns the error, otherwise returns reference to a list of line items suitable for insertion.

LINEITEMREF

An array ref of the line items being billed.

TAXHASHREF

A strange beast. The keys to this hash are internal identifiers consisting of the name of the tax object type, a space, and its unique identifier ( e.g. 'cust_main_county 23' ). The values of the hash are listrefs. The first item in the list is the tax object. The remaining items are either line items or floating point values (currency amounts).

The taxes are calculated on this entity. Calculated exemption records are transferred to the LINEITEMREF items on the assumption that they are related.

Read the source.

INVOICE_TIME

This specifies the date appearing on the associated invoice. Some jurisdictions (i.e. Texas) have tax exemptions which are date sensitive.

_transfer_balance TO_PKG [ FROM_PKGNUM ]

Takes one argument, a cust_pkg object that is being billed. This will be called only if the package was created by a package change, and has not been billed since the package change, and package balance tracking is enabled. The second argument can be an alternate package number to transfer the balance from; this should not be used externally.

Transfers the balance from the previous package (now canceled) to this package, by crediting one package and creating an invoice item for the other. Inserts the credit and returns the invoice item (so that it can be added to an invoice that's being built).

If the previous package was never billed, and was also created by a package change, then this will also transfer the balance from its previous package, and so on, until reaching a package that either has been billed or was not created by a package change.

handle_taxes TAXLISTHASH CUST_BILL_PKG [ OPTIONS ]

This is _handle_taxes. It's called once for each cust_bill_pkg generated from _make_lines.

TAXLISTHASH is a hashref shared across the entire invoice. It looks like this: { 'cust_main_county 1001' => [ [FS::cust_main_county], ... ], 'cust_main_county 1002' => [ [FS::cust_main_county], ... ], }

'cust_main_county' can also be 'tax_rate'. The first object in the array is always the cust_main_county or tax_rate identified by the key.

That "..." is a list of FS::cust_bill_pkg objects that will be fed to the 'taxline' method to calculate the amount of the tax. This doesn't happen until calculate_taxes, though.

OPTIONS may include: - part_item: a part_pkg or part_fee object to be used as the package/fee definition. - location: a cust_location to be used as the billing location. - cancel: true if this package is being billed on cancellation. This allows tax to be calculated on usage charges only.

If not supplied, part_item will be inferred from the pkgnum or feepart of the cust_bill_pkg, and location from the pkgnum (or, for fees, the invnum and the customer's default service location).

This method will also calculate exemptions for any taxes that apply to the line item (using the set_exemptions method of FS::cust_bill_pkg) and attach them. This is the only place set_exemptions is called in normal invoice processing.

_gather_taxes PART_ITEM CLASS CUST_LOCATION

Internal method used with vendor-provided tax tables. PART_ITEM is a part_pkg or part_fee (which will define the tax eligibility of the product), CLASS is 'setup', 'recur', null, or a usage_class number, and CUST_LOCATION is the location where the service was provided (or billed, depending on configuration). Returns an arrayref of FS::tax_rate objects that can apply to this line item.

collect [ HASHREF | OPTION => VALUE ... ]

(Attempt to) collect money for this customer's outstanding invoices (see FS::cust_bill). Usually used after the bill method.

Actions are now triggered by billing events; see FS::part_event and the billing events web interface. Old-style invoice events (see FS::part_bill_event) have been deprecated.

If there is an error, returns the error, otherwise returns false.

Options are passed as name-value pairs.

Currently available options are:

invoice_time

Use this time when deciding when to print invoices and late notices on those invoices. The default is now. It is specified as a UNIX timestamp; see "time" in perlfunc). Also see Time::Local and Date::Parse for conversion functions.

retry

Retry card/echeck/LEC transactions even when not scheduled by invoice events.

check_freq

"1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq)

quiet

set true to surpress email card/ACH decline notices.

debug

Debugging level. Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)

1. =item payby # # allows for one time override of normal customer billing method

retry_realtime

Schedules realtime / batch credit card / electronic check / LEC billing events for for retry. Useful if card information has changed or manual retry is desired. The 'collect' method must be called to actually retry the transaction.

Implementation details: For either this customer, or for each of this customer's open invoices, changes the status of the first "done" (with statustext error) realtime processing event to "failed".

do_cust_event [ HASHREF | OPTION => VALUE ... ]

Runs billing events; see FS::part_event and the billing events web interface.

If there is an error, returns the error, otherwise returns false.

Options are passed as name-value pairs.

Currently available options are:

time

Use this time when deciding when to print invoices and late notices on those invoices. The default is now. It is specified as a UNIX timestamp; see "time" in perlfunc). Also see Time::Local and Date::Parse for conversion functions.

check_freq

"1d" for the traditional, daily events (the default), or "1m" for the new monthly events (part_event.check_freq)

stage

"collect" (the default) or "pre-bill"

quiet

set true to surpress email card/ACH decline notices.

debug

Debugging level. Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)

due_cust_event [ HASHREF | OPTION => VALUE ... ]

Inserts database records for and returns an ordered listref of new events due for this customer, as FS::cust_event objects (see FS::cust_event). If no events are due, an empty listref is returned. If there is an error, returns a scalar error message.

To actually run the events, call each event's test_condition method, and if still true, call the event's do_event method.

Options are passed as a hashref or as a list of name-value pairs. Available options are:

check_freq

Search only for events of this check frequency (how often events of this type are checked); currently "1d" (daily, the default) and "1m" (monthly) are recognized.

stage

"collect" (the default) or "pre-bill"

time

"Current time" for the events.

debug

Debugging level. Default is 0 (no debugging), or can be set to 1 (passed-in options), 2 (traces progress), 3 (more information), or 4 (include full search queries)

eventtable

Only return events for the specified eventtable (by default, events of all eventtables are returned)

objects

Explicitly pass the objects to be tested (typically used with eventtable).

testonly

Set to true to return the objects, but not actually insert them into the database.

apply_payments_and_credits [ OPTION => VALUE ... ]

Applies unapplied payments and credits. Payments with the no_auto_apply flag set will not be applied.

In most cases, this new method should be used in place of sequential apply_payments and apply_credits methods.

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.

apply_credits OPTION => VALUE ...

Applies (see FS::cust_credit_bill) unapplied credits (see FS::cust_credit) to outstanding invoice balances in chronological order (or reverse chronological order if the order option is set to newest) and returns the value of any remaining unapplied credits available for refund (see FS::cust_refund).

Dies if there is an error.

apply_payments [ OPTION => VALUE ... ]

Applies (see FS::cust_bill_pay) unapplied payments (see FS::cust_pay) to outstanding invoice balances in chronological order. Payments with the no_auto_apply flag set will not be applied.

#and returns the value of any remaining unapplied payments.

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.

Dies if there is an error.

FLOW

 bill_and_collect

   cancel_expired_pkgs
   suspend_adjourned_pkgs
   unsuspend_resumed_pkgs

   bill
     (do_cust_event pre-bill)
     _make_lines
       _handle_taxes
         (vendor-only) _gather_taxes
     _omit_zero_value_bundles
     _handle_taxes (for fees)
     calculate_taxes

   apply_payments_and_credits
   collect
     do_cust_event
       due_cust_event

SEE ALSO

FS::cust_main, FS::cust_main::Billing_Realtime