Billing for usage

[Dan Langille]

I think I am fundamentally misunderstanding the Kill Bill approach and that's discouraging.

Some of our plans are fixed rate (e.g. $50/month). Some of them are usage based ($1/1000 widgets).

From what I can see, when a subscription is created, an invoice is created & the payment method is invoked.  An entry is also created in the notification table which triggers the creation of the next invoice. That approach makes sense for fixed rate plans.

What strategy should we adopt for plans which have a usage component?  How does Kill Bill incorporate usage? I suspect I will be referred to the meter plugin (https://github.com/killbill/killbill-meter-plugin).

One objective we were hoping for:  Post charges to the account as the charges are accrued.  e.g. customer does X, gets charged Y.

To that end, I started looking at the API to see what we could use to accomplish that.

I found /1.0/kb/invoices/{invoice-id}/payments?externalPayment=true but that requires you to know the invoice ID in advance (that seems easy enough to do via /1.0/kb/accounts/{accountId}/invoices).  An invoice item added this way is labeled with '(external charge)', which isn't 'pretty'.

I found /1.0/kb/invoices/charges?requestedDate=2014-02-26, but that creates a new invoice every it is invoked.

I found /1.0/kb/invoices?accountId=c1628cfa-1d24-43f4-a109-a08581d13ed6&targetDate=2014-03-01&dryRun=yes but couldn't create an invoice:

21:17:00.570 [qtp452800031-50] WARN  c.n.b.j.mappers.ExceptionMapperBase - Bad request com.ning.billing.invoice.api.InvoiceApiException: No invoice to generate for account c1628cfa-1d24-43f4-a109-a08581d13ed6 and date 2014-02-26 at com.ning.billing.invoice.api.user.DefaultInvoiceUserApi.triggerInvoiceGeneration(DefaultInvoiceUserApi.java:204) ~[killbill-invoice-0.8.12.jar:na]

Am I going about this wrong?

[Pierre-Alexandre Meyer]

On Wed, Feb 26, 2014 at 4:44 PM, Dan Langille <dan.la...@gmail.com> wrote:

I think I am fundamentally misunderstanding the Kill Bill approach and that's discouraging.

Sorry to hear this, let's see if we can help. 

Some of our plans are fixed rate (e.g. $50/month). Some of them are usage based ($1/1000 widgets).

Usage support is currently limited in Kill Bill. We did scope the work and have a good understanding of the problem as well as how to implement it, but we haven't found a sponsor for that work yet.

From what I can see, when a subscription is created, an invoice is created & the payment method is invoked.  An entry is also created in the notification table which triggers the creation of the next invoice. That approach makes sense for fixed rate plans.

Yes. To be precise, the subscription system sends a bus event to which invoice reacts. In turn, besides adding a notification entry for the next bill cycle date, invoice sends an event on the bus as well, which triggers a payment by the payment subsystem (using the default payment method on file).

 

What strategy should we adopt for plans which have a usage component?  How does Kill Bill incorporate usage? I suspect I will be referred to the meter plugin (https://github.com/killbill/killbill-meter-plugin).

The meter plugin implements metering, not usage: metering refers to counting the number of units used by the client (e.g. counting the number of cell phone minutes) whereas usage refers to billing these units (i.e. generating an invoice based on the catalog prices and the number of units collected by the metering subsystem).

The usage piece isn't implemented yet today, and it is not on our short term roadmap. There are workarounds though using external charges (see below).

I found /1.0/kb/invoices/{invoice-id}/payments?externalPayment=true

This is just for external payments, i.e. when a customer doesn't have a credit card (sends checks) and/or when the account is in AUTO_PAY_OFF (payments aren't triggered automatically).

I found /1.0/kb/invoices/charges?requestedDate=2014-02-26, but that creates a new invoice every it is invoked.

If you have an invoice id, you can use POST /1.0/kb/invoices/{invoice-id}/charges to add items to an existing invoice (the body needs to contain at least: accountId, amount and description).

To get the invoice id, either you use an existing one from the account, maybe the one which has the subscription line item (via GET /1.0/kb/accounts/{account-id}/invoices and use the last entry) or create one via /1.0/kb/invoices/{invoice-id}/charges (and re-use it moving forward).

Note that payments aren't triggered automatically when adding external charges, unless you specify payInvoice=true as a query parameter.

I found /1.0/kb/invoices?accountId=c1628cfa-1d24-43f4-a109-a08581d13ed6&targetDate=2014-03-01&dryRun=yes but couldn't create an invoice

This is different: this endpoint is used to trigger invoices for recurring items that weren't generated before (for example, if the account was in AUTO_INVOICING_OFF).

Does this make sense and/or help?

--

Pierre

[Dan Langille]

Pierre: Yes, that is helpful.  I'm going to start exploring the PHP client and keep what you said in mind.  I'll see where that takes me.  Thank you.

[valin...@gmail.com]

Sorry for zombie posting, but this is the discussion with the most relevance to my question.
All data refered to is the current sample data.
I'm testing out killbill for usage + subscription based purposes. The tutorial is fairly enlightening, but I'm stuck on generating an invoice on the fly with a few usage entries on the account. So I have the demo account with a subscription to the standard plan, then updated to "Sports". I added a few usage entries via the tutorial's sample api call. One was from before the account was created, one was a few days after. I have notification enabled, so I got a invoice for $0 when the subscription was changed to 'Sport" and when it was first created as "Standard". I want to now trigger invoice generation with the two usage charges of 1 gallon each on the invoice. I get the following:

2015-03-19 11:38:59,231 [qtp7868747-19] INFO o.k.b.invoice.InvoiceDispatcher - Generated null invoice for accountId 72a775a2-de30-4d9b-ace0-9aa5227729bd and targetDate 2015-04-14 (targetDateTime 2015-04-14T16:38:58.434Z)
2015-03-19 11:38:59,256 [qtp7868747-19] INFO c.s.j.a.c.filter.LoggingFilter - 164 * Server out-bound response
164 < 404
164 < Content-Type: application/json
164 <

Not sure what is happening here.

I added a "gas-monthly" addon to the plan (but in the kaui it shows up as "gas (no billing period)"), and the resultant log output is the same.
If, following the original response here, I add charges to an existing invoice, would I not be changing an invoice which already have a notification that has gone out? Or perhaps the answer is to create a dry-run invoice and then add charges to that? If so, how does automated invoice generation work for usage billing? on the due date, does the subscription based invoice get generated, and then the usage tagged on automatically?

[Pierre-Alexandre Meyer]

On Thu, Mar 19, 2015 at 12:47 PM, <valin...@gmail.com> wrote:

I get the following:

2015-03-19 11:38:59,231 [qtp7868747-19] INFO  o.k.b.invoice.InvoiceDispatcher - Generated null invoice for accountId 72a775a2-de30-4d9b-ace0-9aa5227729bd and targetDate 2015-04-14 (targetDateTime 2015-04-14T16:38:58.434Z)
2015-03-19 11:38:59,256 [qtp7868747-19] INFO  c.s.j.a.c.filter.LoggingFilter - 164 * Server out-bound response
164 < 404
164 < Content-Type: application/json
164 <

Not sure what is happening here.

The 404 means that there is nothing to generate ("null" invoice). For consumable in arrear usage items, they will be charged at the end of the billing period. When you trigger the invoice manually, make sure to set a target date of at least the next BCD of the account (or bundle/subscription, depending on your alignment).

--

Pierre