BillSoft

Overview

jBilling comes ‘out of the box’ with simple tax functionality. This means that without any customization, the system can handle the application of very basic taxes through the use of plugins.

One of the ways in which the system can handle simple taxes is to use the CountryTaxCompositionTask plugin, which will automatically assign country specific taxes for all products. The logic for this feature is based on the country code assigned to the customer. Alternatively, it is also possible to add a specific tax to a group of products. This can be done by using the SimpleTaxCompositionTask plugin. This plugin also provides the user with the ability to exempt products and customers from receiving tax. However, depending on how complex the taxes are, this plugin does not provide an easy way to apply taxes based on where the customer lives.

Applying taxes correctly is critical for all industries, but there are many complications when it comes to applying taxes to products and services for Telco. Compliancy is non negotiable, so when customers who reside in the United States are invoiced it can be incredibly time consuming to ensure that taxes are applied correctly. For example, federal, state, and local taxes are applied to all different combinations of services and products. One type of tax a particular customer needs, may not apply to the other. Additional types of taxes include: sales tax, telecommunications excise tax, utility users tax, business and occupations tax, gross receipt tax, and 911 fees.

Many billing systems attempt to handle taxes by using rate tables. The problem with this approach is that it does not take into account the plethora of scenarios a tax engine was built to handle with ease. As jBilling is a highly flexible and extensible system, with a complete API, our approach was to simply integrate with BillSoft.

BillSoft

In order to initiate the plug-in, we first require a “Base Tax” product. When the plug-in adds tax lines to an order, it will use the base product to provide a product ID for the order line. Each tax line will contain the appropriate description and dollar value for the applied taxes.

You need to configure the EZTaxOrderTask plug-in in order to use it. It is provided in jBilling as a single plug-in that implements two separate plug-in interfaces. This means that it is one piece of code that fills the needs of both plug-ins. jBIlling doesn’t support multitasking plug-ins, so it will appear as though there are two identical classes in the plug-in list. Both will need to be configured.

Optional EZTaxOrderTask Parameters:

There are a few parameters associated to these plug-ins:

  • Business - is the requesting entity a business?
  • Incorporated - is the requesting entity incorporated?
  • Regulated - is the requesting entity a regulated service?
  • Sale - is this a sale transaction?
  • Federal Exempt - does the requesting entity have a federal tax exempt status?
  • State Exempt - does the requesting entity have a state tax exempt status?
  • Country Exempt - is the requesting entity exempt from country taxes?
  • Local Exempt - is the requesting entity exempt from local taxes?
  • Use Parent Address - attempt to resolve address from parent users?
  • Re-tax Invoice - discard all taxes and reprocess when an order is being added to an invoice?
  • Retax Order - discard all taxes and reprocess when an existing order is being modified?

The BillSoft plug-in will pull BillSoft ‘Service Type’ and ‘Transaction Type’ codes from a product's category description. To assign these codes to an product within jBilling, you will need to add additional product types and assign these types to call products.

EZTax Logic (tax is added when...)

As mentioned above, the EZTaxOrderTask task is technically two separate plug-ins. They are, OrderProcessingTask and InternalEventsTask, rolled into one class.

The tax logic triggers on the OrderProcessingTask when:

  • An invoice total is re-calculated
  • Orders are created manually or via the API
  • A recalculation is called manually or via the API

InternalEventsTask’s are subscribed to the OrderToInvoiceEvent when:

  • An order is added to the billable invoice - Note: this excludes review invoices
  • Review invoice creation does not emit a OrderToInvoiceEvent - no taxes will be added.

jBilling doesn’t emit an OrderToInvoiceEvent for review invoices because it does not represent the final invoice. Any edits made to the order at this time may generate incorrect results when the final billable invoice is created.

EZTax Request Address

when "use parent address" is false

By default, the EZTax plug-in will use the address of the user who owns the purchase order. Only when the ‘use parent address’ parameter is set to true will EZTax attempt to resolve the billing address from a parent user.

when "use parent address" is true

For every request, jBilling sends the address of the customer to EXTax so that the returned taxes will be appropriate to the customers location. In order to determine the address, jBilling searches through the parent accounts of a user until it finds one with the "Invoice if child" field selected (or the topmost "Tier 1" user).

This means that the "Invoice if child" flag is set for the user account whose address you want to use for taxes. All accounts under this "Invoice if child" user will use that address when requesting taxes from EZTax.

Using Specific Tax Products (GL Code support)

To use specific tax products, you can add a plug-in parameter that will map a BillSoft tax type to a specific product ID. These mapping parameters use a name with the BillSoft tax type, and is prefixed by "tax type", and the corresponding jBilling product ID as the value. For example: Parameter "tax_type_10", value "401" would map BillSoft tax type 10 to jBilling product 401.

To assign a GL code to a tax, you simply need to create a Tax product with a GL code, and use the mapping parameter to assign the product to a BillSoft tax type. When the EZTaxOrderTask plug-in adds a tax line it will then add specific jBilling products to the order that have GL codes attached.