Difference between revisions of "Freeside:3:Documentation:Developer/FS/cust main/Billing"
From Freeside
m (Edit via perl MediaWiki framework (1.13)) |
m (Edit via perl MediaWiki framework (1.13)) |
||
| Line 74: | Line 74: | ||
:; invoice_terms | :; invoice_terms | ||
::Optional terms to be printed on this invoice. Otherwise, customer-specific terms or the default terms are used. | ::Optional terms to be printed on this invoice. Otherwise, customer-specific terms or the default terms are used. | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
; _transfer_balance TO_PKG [ FROM_PKGNUM ] | ; _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. | :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. | ||
| Line 106: | Line 92: | ||
: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). | :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). | ||
| − | |||
| − | |||
; _gather_taxes PART_ITEM CLASS CUST_LOCATION | ; _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 <tt>usage_class</tt> number, and CUST_LOCATION is the location where the service was provided (or billed, depending on configuration). Returns an arrayref of [[Freeside:3:Documentation:Developer/FS/tax rate|FS::tax_rate]] objects that can apply to this line item. | :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 <tt>usage_class</tt> number, and CUST_LOCATION is the location where the service was provided (or billed, depending on configuration). Returns an arrayref of [[Freeside:3:Documentation:Developer/FS/tax rate|FS::tax_rate]] objects that can apply to this line item. | ||
| Line 207: | Line 191: | ||
(do_cust_event pre-bill) | (do_cust_event pre-bill) | ||
_make_lines | _make_lines | ||
| − | |||
| − | |||
_omit_zero_value_bundles | _omit_zero_value_bundles | ||
| − | |||
calculate_taxes | calculate_taxes | ||
Revision as of 06:39, 24 March 2015
Contents
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).
- 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.
- _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).
- _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)
- =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
_omit_zero_value_bundles
calculate_taxes
apply_payments_and_credits
collect
do_cust_event
due_cust_event
