Difference between revisions of "Freeside:3:Documentation:Developer/FS/cust main/Billing"

Revision as of 20:07, 27 June 2012

NAME

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

SYNOPSIS

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).

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

This is a weird one. Perhaps it should not even be exposed.

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.

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.

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.

#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
     calculate_taxes

   apply_payments_and_credits
   collect
     do_cust_event
       due_cust_event

BUGS

SEE ALSO

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