Overview
InvoicePluginApi
The InvoicePluginApi exists to develop invoice plugins. Those plugins are called from the core invoice system each time a new invoice is being generated by the system: The invoice system will first compute all the items based on the existing subscriptions or usage data associated to the account and then invoke the registered plugins to allow to add extra items on that invoice.
Plugins need to implement one api getAdditionalInvoiceItems, whose purpose is to to allow plugins to add additional items and which takes the following parameters:
-
invoice: A copy of the current invoice being generated by the system (including all items generated by the system, and only items generated by the system) -
properties: An empty list ofPluginProperty, which means this field exists only for symmetry with other plugin apis, but is not used. -
context: The call context associated to that invoice (mostly interesting for plugins to identify the tenant)
If multiple plugins have been registered, the system will invoke all of them in no particular order. Each plugin will only see the original items generated by the system, but the union of all items generated by all plugins would end up on the invoice.
Plugins are restricted in the type of items they can add because some items (e.g RECURRING) need to match existing subscription or usage data associated to the account. The following types are allowed:
-
EXTERNAL_CHARGE -
ITEM_ADJ -
TAX
Plugin Activation
Kill Bill will invoke each of the invoice plugins registered in the system when a new invoice gets generated or when a user issues a refund. The order in which those plugins are invoked is not well specified (We also have never seen use cases where there was a need for multiple invoice plugins).
Use Cases
Tax Plugin
One of the main use case of this api is to allow plugins to add TAX items. Kill Bill by default knows nothing about tax, and that logic is deferred to plugins implementing this api. Example of such existing plugins are:
-
Avalara tax plugin: This is a plugin that interracts with the third party
Avalara. -
Simple tax plugin: This is a simple tax plugin that was developed mostly as a use case for the api or to address use cases where tax calculation is simple.
Invoice Customization
There are many use cases where one would want to modify existing invoices. For instance one could implement a way to generate discounts based on certain heuristics (for a given tenant/account/subscription some discount could apply). In those scenarios, the plugin would add ITEM_ADJ items to reflect the discount.
A reverse use case is one where a plugin needs to add extra charges that are unknown of the system (Kill Bill) and also based on some heuristics that are only known from the plugin.