This document provides information about Kill Bill events and their metadata.
Kill Bill generates some events when certain actions occur within the system. For example, an event is generated when a new account is created, when a new subscription is created and so on. Such events can be used to build notification plugins. Applications can also use the push notifications feature to subscribe to such events via HTTP.
Ensure that you have gone through the What is Kill Bill guide and have a fair idea about what Kill Bill is and how it works.
As explained earlier, Kill Bill generates different events when different actions occur within the system. An event is actually an object of the type ExtBusEvent.
event object has the following fields:
eventType: type of event (as defined by the ExtBusEventType enum)
objectType: type of object being updated/modified (as defined by the ObjectType enum)
accountId: account id associated with the object
objectId: id of the object being created/modified
metaData: event-specific metadata. By design, events are generic and contain very limited information. In some cases however, specific events may contain further information in the
metaDatacan either be a simple String value or a JSON representation of a metadata object).
tenantId: tenant id associated with the object
userToken: user token in the API request
The following table provides details of all the events and their metadata.
|Event Name||Event Generation Condition||Object||Metadata|
A new customer account is created
A customer account is modified
There is a change in the state of an entitlement or billing. See Blocking States to know more
Used to broadcast an event to other Kill Bill nodes (Typically used for plugin related events like plugin installation, plugin uninstallation, plugin start, plugin stop, etc.)
A new subscription is created
A subscription transitions into a different phase
A subscription is modified
A subscription is cancelled
A subscription cancellation is undone (Note that subscription cancellation cannot be undone once the cancellation becomes effective)
The subscription BCD is changed
A new entitlement is created
An entitlement is cancelled
A subscription bundle is paused
A subscription bundle is resumed
There is a change is an overdue state
A new invoice is generated
An invoice is adjusted
An invoice is going to be generated for an account in the future (Can be used to notify customers about upcoming bills)
An invoice payment is successful
An invoice payment fails
Payment is successful
A new tag is associated with a Kill Bill resource (account, invoice, etc.)
A tag associated with a Kill Bill resource (account, invoice, etc.) is deleted
A custom field is created
A custom field is deleted
A Tenant configuration is modified (So, any changes to a catalog, overdue config, etc. within a tenant triggers this event)
A Tenant configuration is deleted
Let us now take a quick look at some of the metadata objects.
The SubscriptionMetadata object is used to specify the metadata in case of the
It has the following fields:
actionType: Specifies whether the event is effective right away (
EFFECTIVE) or is scheduled for the future (
bundleExternalKey: Specifies the subscription bundle external key
The PaymentMetadata object is used to specify the metadata in case of the
It has the following fields:
paymentTransactionId: Specifies the id of the payment transaction
amount: Specifies the amount in this payment object
currency: Specifies the currency used for payment
status: Specifies the payment transaction status (
transactionType: Specifies the payment transaction type (
effectiveDate:Specifies the date when the payment becomes effective.