Template Invoice/Crediting questions/Bulk external charge items submission

379 views
Skip to first unread message

Mouhammed Soueidane

unread,
Apr 15, 2014, 4:00:49 PM4/15/14
to killbill...@googlegroups.com
Hello guys,
I have a few questions:

1- When crediting an account or an invoice, and when the balance of the account becomes negative, Kill-Bill tends to add a new Invoice Item against the existing external charge items with the description: Description is Adjustment (use of account credit). We just want to see if the wording of the description can be changed since it might be a bit confusing for some customers

2- When crediting an account (At the account level), Kill-Bill creates an empty invoice with a CBA amount. When listing invoices to our customers, we don't want to display these invoices to them. Is there a way to differentiate invoices that were created by us, and others that were created automatically by Kill-Bill?

3- I know that we have requested this before, but the need for this feature has now become really needed: We need to be able to create an invoice with a bulk of external charge items, instead of having to make one call for every external charge item that we need to add to an invoice. Is this going to be added any time soon?

4- Since Kill-Bill doesn't support creating a recurrent invoice with a fixed set of external charge items (Something that we really need), we have created a standalone Java application that would check our local database for invoices that were marked as "recurrent", and on a Monthly basis, it will get the invoice information from Kill-Bill (Specifically the external charge items) and creates a new invoice using the old one as a template. This however requires us to create an invoice on Kill-Bill first and then mark it as recurrent in our local database. What we are after is a means of creating an invoice on Kill-Bill that will work as a template without charging the customer for it, and on a monthly basis, our scheduler would create invoices from this template but this time the customers will be charged for the invoices that were created from the template. I hope this makes sense for you. 

Thanks for your help guys.

Pierre-Alexandre Meyer

unread,
Apr 16, 2014, 7:04:56 AM4/16/14
to Mouhammed Soueidane, killbill...@googlegroups.com
On Tue, Apr 15, 2014 at 4:00 PM, Mouhammed Soueidane <m.sou...@gmail.com> wrote:
1- When crediting an account or an invoice, and when the balance of the account becomes negative, Kill-Bill tends to add a new Invoice Item against the existing external charge items with the description: Description is Adjustment (use of account credit). We just want to see if the wording of the description can be changed since it might be a bit confusing for some customers


To configure a custom template, specify the location via the org.killbill.template.name system property (for Kill Bill 0.8 and before, the property name is killbill.template.name).
 
If you are not familiar with Mustache, see http://mustache.github.io/.

2- When crediting an account (At the account level), Kill-Bill creates an empty invoice with a CBA amount. When listing invoices to our customers, we don't want to display these invoices to them.

I'm curious, why don't you want to display them? CBA, i.e. credits, is actual money flowing from the customer to you (use of account credit) or the other way around (when giving credit). Shouldn't the customer understand where the money comes from?
 
Is there a way to differentiate invoices that were created by us, and others that were created automatically by Kill-Bill?

This is where audit logs could help you. When listing all invoices for an account (GET /1.0/kb/accounts/{accountId}/invoices), you can specify the query parameter audit=FULL. Assuming you use a sensible reason/comment when you created the credit, you can filter them out when retrieving them.
 
3- I know that we have requested this before, but the need for this feature has now become really needed: We need to be able to create an invoice with a bulk of external charge items, instead of having to make one call for every external charge item that we need to add to an invoice. Is this going to be added any time soon?

Yes, we've had also another user requesting this feature recently. I can't give you an exact timeframe though.

How is your launch date looking? It would be great if we could help you upgrade to 0.10.x before, so you can benefit from the latest features (we'd like to avoid backporting them to 0.8.x).

4- Since Kill-Bill doesn't support creating a recurrent invoice with a fixed set of external charge items (Something that we really need),

Kill Bill 0.10.x now has usage support (Consumable in Arrear, see http://thekillbillstory.wordpress.com/2014/03/11/usage-billing/). Would this help your usecase? (we can help you design the catalog)
 
What we are after is a means of creating an invoice on Kill-Bill that will work as a template without charging the customer for it, and on a monthly basis, our scheduler would create invoices from this template but this time the customers will be charged for the invoices that were created from the template.

What do you mean by 'template'? Which information do you need from that first invoice that you cannot re-create on a monthly basis?

By the way, where are you based? We are currently planning some international trips for various conferences and I'm curious if we could meet up!

Cheers,

--
Pierre

Mouhammed Soueidane

unread,
Apr 16, 2014, 1:51:08 PM4/16/14
to killbill...@googlegroups.com, Mouhammed Soueidane
To configure a custom template, specify the location via the org.killbill.template.name system property (for Kill Bill 0.8 and before, the property name is killbill.template.name).
If you are not familiar with Mustache, see http://mustache.github.io/.

I didn't quite understand what you meant with "HTML invoice template" but I guess that this is a homework that I should be doing to better understand this. I will let you know if what you suggested tackles the problem I addressed. 
 
I'm curious, why don't you want to display them? CBA, i.e. credits, is actual money flowing from the customer to you (use of account credit) or the other way around (when giving credit). Shouldn't the customer understand where the money comes from?
 
I think that the reason why I was asked for this is that we currently display invoices in a grid in our web application, and currently, invoices that contain credits only would display a negative amount in them, which could be a bit confusing for the customers. 

This is where audit logs could help you. When listing all invoices for an account (GET /1.0/kb/accounts/{accountId}/invoices), you can specify the query parameter audit=FULL. Assuming you use a sensible reason/comment when you created the credit, you can filter them out when retrieving them.

Oh I understand. I never thought that I would need to set my reason and comment fields. I will give it a try and let you know what happens. 
 

How is your launch date looking? It would be great if we could help you upgrade to 0.10.x before, so you can benefit from the latest features (we'd like to avoid backporting them to 0.8.x).
We have a plan of starting to stage at the end of April ( We still don't have anything in production ). This means that we currently have the luxury to drop kill bill 0.8.12 and use 0.10.12 without thinking much about the upgrade. I actually started the upgrade process, and just when I was about to get the new Java-API for it, I realized that it's not there. I checked the page https://github.com/killbill/killbill-api/releases and couldn't find it there. Is it going to be available anytime soon?

Kill Bill 0.10.x now has usage support (Consumable in Arrear, see http://thekillbillstory.wordpress.com/2014/03/11/usage-billing/). Would this help your usecase? (we can help you design the catalog)
We see ourselves using usage-billing in the future for sure. But for the time being, and as a first phase, we need a means of creating invoices with external charges on a recurrent basis (Something that Stephane has already confirmed for us that's not supported by Kill-Bill). I don't think that a catalog would solve my problem since I expect an admin user to charge the customers for items that are not in the catalog ( Hence our using of the external charge items)

What do you mean by 'template'? Which information do you need from that first invoice that you cannot re-create on a monthly basis?
An invoice template would be an invoice that contains the external charge items with their information (Amount and description mostly). We need to be able to create a "real" invoice from this template (Same external charge items and balance) on a recurrent basis (Monthly for example)
 
By the way, where are you based? We are currently planning some international trips for various conferences and I'm curious if we could meet up!
I'm currently a developer working on the project. I live in Lebanon (Middle east). The company I work for is based in Canada. It would be great to meet you guys in person.

Pierre-Alexandre Meyer

unread,
Apr 16, 2014, 4:19:10 PM4/16/14
to Mouhammed Soueidane, killbill...@googlegroups.com
On Wed, Apr 16, 2014 at 1:51 PM, Mouhammed Soueidane <m.sou...@gmail.com> wrote:
I didn't quite understand what you meant with "HTML invoice template" but I guess that this is a homework that I should be doing to better understand this. I will let you know if what you suggested tackles the problem I addressed. 

How do you present the invoice to the user?

Kill Bill has a special endpoint (/1.0/kb/invoices/{invoiceId}/html) your web application can use to render invoices as HTML pages. To configure the presentation (to put your company logo, configure the information which should be displayed, add custom text, etc.), you can specify a Mustache template which is used to render the HTML.

If you have Kaui up and running, on an invoice screen, you can click the "Display invoice as HTML" button to get a preview.

By the way, you can also configure Kill Bill to send these invoices as formatted emails.
 
This is where audit logs could help you. When listing all invoices for an account (GET /1.0/kb/accounts/{accountId}/invoices), you can specify the query parameter audit=FULL. Assuming you use a sensible reason/comment when you created the credit, you can filter them out when retrieving them.

Oh I understand. I never thought that I would need to set my reason and comment fields. I will give it a try and let you know what happens. 

Reason and comment are useful for many purposes. Besides embedding custom logic as I was suggesting, they can be useful for your finance department for example: you can categorize refunds using internal reason codes, which makes financial reporting easier, or add one-off comments for special operations, such as pro-rating an invoice for a given customer because your website was down for a day or two.
 
They are also integrated with Kaui (certain screens let you configure mandatory reason codes and/or comments the operator needs to set).

 I actually started the upgrade process, and just when I was about to get the new Java-API for it, I realized that it's not there. I checked the page https://github.com/killbill/killbill-api/releases and couldn't find it there. Is it going to be available anytime soon?

The different Kill Bill sub-projects are versioned independently (killbill 0.10.x doesn't mean it's using killbill-api 0.10.x). The latest Kill Bill API (0.8.3) is compatible with 0.10.x (Kill Bill server).

Kill Bill 0.10.x now has usage support (Consumable in Arrear, see http://thekillbillstory.wordpress.com/2014/03/11/usage-billing/). Would this help your usecase? (we can help you design the catalog)
We see ourselves using usage-billing in the future for sure. But for the time being, and as a first phase, we need a means of creating invoices with external charges on a recurrent basis (Something that Stephane has already confirmed for us that's not supported by Kill-Bill). I don't think that a catalog would solve my problem since I expect an admin user to charge the customers for items that are not in the catalog ( Hence our using of the external charge items)

What is the reason for the items not to be in the catalog? Are they dynamic? I'm just trying to understand better your usecase to see if we can find a workaround.

What do you mean by 'template'? Which information do you need from that first invoice that you cannot re-create on a monthly basis?
An invoice template would be an invoice that contains the external charge items with their information (Amount and description mostly). We need to be able to create a "real" invoice from this template (Same external charge items and balance) on a recurrent basis (Monthly for example)

Sorry, I'm still having a hard time understanding the usecase. What I understand is that you have a fix set of charges (amount + description) you want to charge a customer on a recurring basis, let's say C1 for $10 and C2 for $20.

Do these amounts change or for every month will the customer be charged for $30? Why do you need this 'template' invoice? Is it to keep track of C1 and C2 per customer?

Would a dynamic catalog help you? Imagine having an API to create a recurring monthly plan P which would charge two subscriptions, C1 for $10 and C2 for $20. Would subscribing the user to that plan solve your usecase?
 
By the way, where are you based? We are currently planning some international trips for various conferences and I'm curious if we could meet up!
I'm currently a developer working on the project. I live in Lebanon (Middle east). The company I work for is based in Canada. It would be great to meet you guys in person.

I might be in Tel Aviv in July for a Bitcoin conference (http://www.mediabistro.com/insidebitcoins/). Happy to hop over to Lebanon if it's confirmed. Of course, if you end up visiting the Canada office, ping us ;-)

--
Pierre

Pierre-Alexandre Meyer

unread,
Apr 17, 2014, 9:55:03 AM4/17/14
to Mouhammed Soueidane, killbill...@googlegroups.com
On Wed, Apr 16, 2014 at 7:04 AM, Pierre-Alexandre Meyer <pie...@kill-bill.org> wrote:
3- I know that we have requested this before, but the need for this feature has now become really needed: We need to be able to create an invoice with a bulk of external charge items, instead of having to make one call for every external charge item that we need to add to an invoice. Is this going to be added any time soon?

Yes, we've had also another user requesting this feature recently. I can't give you an exact timeframe though.

Quick follow-up on this: we started the implementation in the bulk-external-charges branch:


This triggered a few API/design questions we need to sort through, but hopefully it'll be in 0.10.3 or 0.10.4.

--
Pierre

Mouhammed Soueidane

unread,
Apr 20, 2014, 7:03:28 PM4/20/14
to killbill...@googlegroups.com, Mouhammed Soueidane


On Wednesday, 16 April 2014 23:19:10 UTC+3, Pierre-Alexandre Meyer wrote:
On Wed, Apr 16, 2014 at 1:51 PM, Mouhammed Soueidane <m.sou...@gmail.com> wrote:
I didn't quite understand what you meant with "HTML invoice template" but I guess that this is a homework that I should be doing to better understand this. I will let you know if what you suggested tackles the problem I addressed. 

How do you present the invoice to the user?

Kill Bill has a special endpoint (/1.0/kb/invoices/{invoiceId}/html) your web application can use to render invoices as HTML pages. To configure the presentation (to put your company logo, configure the information which should be displayed, add custom text, etc.), you can specify a Mustache template which is used to render the HTML.

If you have Kaui up and running, on an invoice screen, you can click the "Display invoice as HTML" button to get a preview.

By the way, you can also configure Kill Bill to send these invoices as formatted emails.
 
This is where audit logs could help you. When listing all invoices for an account (GET /1.0/kb/accounts/{accountId}/invoices), you can specify the query parameter audit=FULL. Assuming you use a sensible reason/comment when you created the credit, you can filter them out when retrieving them.

Oh I understand. I never thought that I would need to set my reason and comment fields. I will give it a try and let you know what happens. 

Reason and comment are useful for many purposes. Besides embedding custom logic as I was suggesting, they can be useful for your finance department for example: you can categorize refunds using internal reason codes, which makes financial reporting easier, or add one-off comments for special operations, such as pro-rating an invoice for a given customer because your website was down for a day or two.
 
  I'm seeing the bigger picture now, many thanks for pointing this out. Things are much simpler on our end for now. We might need this in the future however. 
They are also integrated with Kaui (certain screens let you configure mandatory reason codes and/or comments the operator needs to set).

 I actually started the upgrade process, and just when I was about to get the new Java-API for it, I realized that it's not there. I checked the page https://github.com/killbill/killbill-api/releases and couldn't find it there. Is it going to be available anytime soon?

The different Kill Bill sub-projects are versioned independently (killbill 0.10.x doesn't mean it's using killbill-api 0.10.x). The latest Kill Bill API (0.8.3) is compatible with 0.10.x (Kill Bill server).
   Taking this versioning approach is a bit confusing. We would have to remember two versions (That of the API and that of the killl bill server). Not a deal-breaker though =) 

Kill Bill 0.10.x now has usage support (Consumable in Arrear, see http://thekillbillstory.wordpress.com/2014/03/11/usage-billing/). Would this help your usecase? (we can help you design the catalog)
We see ourselves using usage-billing in the future for sure. But for the time being, and as a first phase, we need a means of creating invoices with external charges on a recurrent basis (Something that Stephane has already confirmed for us that's not supported by Kill-Bill). I don't think that a catalog would solve my problem since I expect an admin user to charge the customers for items that are not in the catalog ( Hence our using of the external charge items)

What is the reason for the items not to be in the catalog? Are they dynamic? I'm just trying to understand better your usecase to see if we can find a workaround.

  Yes exactly. We expect the users to input any kind of items in here. Again this is why we're using external charge items rather than having a predefined catalog for them.
 
What do you mean by 'template'? Which information do you need from that first invoice that you cannot re-create on a monthly basis?
An invoice template would be an invoice that contains the external charge items with their information (Amount and description mostly). We need to be able to create a "real" invoice from this template (Same external charge items and balance) on a recurrent basis (Monthly for example)

Sorry, I'm still having a hard time understanding the usecase. What I understand is that you have a fix set of charges (amount + description) you want to charge a customer on a recurring basis, let's say C1 for $10 and C2 for $20.

 
Well, I'll explain the usecase in further detail:
1- An admin user creates an invoice for one of our customers.
2- In the invoice creation page, the admin user can add as many items as they want (The list of available items is not preset. An admin user has two free text fields to fill which are description and amount, same as an InvoiceItem)
3- After adding all the invoice items, and before clicking on (Create invoice), the admin user has two choices: He can either choose that this invoice is recurrent on a monthly basis, or he can choose that this is not recurrent. If he chooses that the current invoice is a recurrent one, he will be asked to enter a start date for it. So if he enters tomorrow as a start date and then clicks on "Create Invoice", the customer will not be charged for the invoice till we reach the start date. The invoice will be created when we reach the start date, and an e-mail with the invoice information will be sent to the customer. Then, we expect this invoice to be automatically created for the customer on a monthly basis (E-mails will be sent to the customer informing him/her that a new invoice is due). If the admin user doesn't indicate that this is a recurrent invoice and clicks on "Create Invoice", the customer will be instantly charged for the invoice, and an e-mail will instantly be sent to the customer with the invoice information.

I hope that it makes much more sense now.

Do these amounts change or for every month will the customer be charged for $30? Why do you need this 'template' invoice? Is it to keep track of C1 and C2 per customer?

As I explained in the previous point, we need this "Template Invoice" when the "Recurrent" option is chosen for an invoice. This same invoice (With the same invoice items) will be created for this specific customer on a monthly basis.
 
Would a dynamic catalog help you? Imagine having an API to create a recurring monthly plan P which would charge two subscriptions, C1 for $10 and C2 for $20. Would subscribing the user to that plan solve your usecase?
   
Well the invoice is not part of a plan or anything. It just contains invoice items that are not preset. They could be anything. An example of invoice items would be "Changing RJ-45 cables", "Installed/Customized firewall configuration"...
 
 
By the way, where are you based? We are currently planning some international trips for various conferences and I'm curious if we could meet up!
I'm currently a developer working on the project. I live in Lebanon (Middle east). The company I work for is based in Canada. It would be great to meet you guys in person.

I might be in Tel Aviv in July for a Bitcoin conference (http://www.mediabistro.com/insidebitcoins/). Happy to hop over to Lebanon if it's confirmed. Of course, if you end up visiting the Canada office, ping us ;-)

Lebanon is currently in a state of war with Israel. I think that if your passport contains any references to Israel that you won't be allowed to enter the Lebanese territory. I think that there are better odds that we'd meet in Canada, hopefully a few months from now =)

Pierre-Alexandre Meyer

unread,
Apr 21, 2014, 7:06:31 AM4/21/14
to Mouhammed Soueidane, killbill...@googlegroups.com
On Sun, Apr 20, 2014 at 7:03 PM, Mouhammed Soueidane <m.sou...@gmail.com> wrote:
The different Kill Bill sub-projects are versioned independently (killbill 0.10.x doesn't mean it's using killbill-api 0.10.x). The latest Kill Bill API (0.8.3) is compatible with 0.10.x (Kill Bill server).
   Taking this versioning approach is a bit confusing. We would have to remember two versions (That of the API and that of the killl bill server). Not a deal-breaker though =) 

Actually, you should never have to worry about killbill-api. This is the API of the Kill Bill Java library, for deployments where Kill Bill is embedded in a Java application.

Since you are using Kill Bill server, you never interact with killbill-api directly. Instead, you use the JAX-RS REST HTTP APIs, which share the same version as Kill Bill server (and can be found at https://github.com/killbill/killbill/tree/master/jaxrs/src/main/java/org/killbill/billing/jaxrs/resources).

Also, since you are using the Java client, that complexity is also hidden from you. Getting the latest Java client and Kill Bill server should be all you need from a coding perspective. You also need to get the latest DDL from http://docs.kill-bill.org/schema.html.

Sorry, I'm still having a hard time understanding the usecase. What I understand is that you have a fix set of charges (amount + description) you want to charge a customer on a recurring basis, let's say C1 for $10 and C2 for $20.

 
Well, I'll explain the usecase in further detail:
1- An admin user creates an invoice for one of our customers.
2- In the invoice creation page, the admin user can add as many items as they want (The list of available items is not preset. An admin user has two free text fields to fill which are description and amount, same as an InvoiceItem)
3- After adding all the invoice items, and before clicking on (Create invoice), the admin user has two choices: He can either choose that this invoice is recurrent on a monthly basis, or he can choose that this is not recurrent. If he chooses that the current invoice is a recurrent one, he will be asked to enter a start date for it. So if he enters tomorrow as a start date and then clicks on "Create Invoice", the customer will not be charged for the invoice till we reach the start date. The invoice will be created when we reach the start date, and an e-mail with the invoice information will be sent to the customer. Then, we expect this invoice to be automatically created for the customer on a monthly basis (E-mails will be sent to the customer informing him/her that a new invoice is due). If the admin user doesn't indicate that this is a recurrent invoice and clicks on "Create Invoice", the customer will be instantly charged for the invoice, and an e-mail will instantly be sent to the customer with the invoice information.

I hope that it makes much more sense now.

It does, thanks for the detailed explanation.

I have a couple of follow-up questions. First of all, you mention the admin user can enter anything (free text fields). This makes sense for one-time charges (e.g. changing RJ-45 cables) and that's exactly what external charges were designed for. However, I'm trying to understand if the set of recurring charges are really generic? If you are providing hosting services, the type of servers, software, etc. you offer is fairly static, no?

To make it more concrete, if somebody wants to rent five small (S) servers, one firewall (F) and one load-balancer (LB), I can see the following happening: the user is charged for various setup fees (one time), such as configuring the firewall, putting the hardware in place, etc. And he would be charged on a monthly basis for the servers, firewall and load-balancer.

In that scenario, creating entries (plans) for all of your recurring items would solve your problem. The catalog would have three plans, one for S, one for F and one for LB (each with its own price). The recurring invoice creation step you mentioned would be to subscribe the user to these three plans, and the flow you described would just work.

Why can't you create such plans? Is it because the pricing of each plan is dynamic and depends on the customer?

In case you cannot, having the dynamic catalog feature would solve your problem. This is a feature we've talked about implementing, where Kill Bill would have an API to create plans on the fly. On the recurring invoice creation step you mentioned, your application could take the content of the text fields, create a plan on the fly for it, and subscribe the user to it. The user would have one or multiple subscriptions to custom plans, and Kill Bill would invoice the user on a monthly basis.

What have you implemented now? Do you have a custom recurring engine already?

Lebanon is currently in a state of war with Israel. I think that if your passport contains any references to Israel that you won't be allowed to enter the Lebanese territory. I think that there are better odds that we'd meet in Canada, hopefully a few months from now =)

I suppose you're right. Let us know when you are in Canada!

--
Pierre

Pierre-Alexandre Meyer

unread,
Apr 27, 2014, 9:10:46 AM4/27/14
to Mouhammed Soueidane, killbill...@googlegroups.com
On Mon, Apr 21, 2014 at 7:06 AM, Pierre-Alexandre Meyer <pie...@kill-bill.org> wrote:
On Sun, Apr 20, 2014 at 7:03 PM, Mouhammed Soueidane <m.sou...@gmail.com> wrote:
The different Kill Bill sub-projects are versioned independently (killbill 0.10.x doesn't mean it's using killbill-api 0.10.x). The latest Kill Bill API (0.8.3) is compatible with 0.10.x (Kill Bill server).
   Taking this versioning approach is a bit confusing. We would have to remember two versions (That of the API and that of the killl bill server). Not a deal-breaker though =) 

Actually, you should never have to worry about killbill-api. This is the API of the Kill Bill Java library, for deployments where Kill Bill is embedded in a Java application.

Since you are using Kill Bill server, you never interact with killbill-api directly. Instead, you use the JAX-RS REST HTTP APIs, which share the same version as Kill Bill server (and can be found at https://github.com/killbill/killbill/tree/master/jaxrs/src/main/java/org/killbill/billing/jaxrs/resources).

Also, since you are using the Java client, that complexity is also hidden from you. Getting the latest Java client and Kill Bill server should be all you need from a coding perspective. You also need to get the latest DDL from http://docs.kill-bill.org/schema.html.

We have started a wiki page to clarify this information, see:


Feedback welcome!

--
Pierre

Pierre-Alexandre Meyer

unread,
Apr 27, 2014, 9:14:05 AM4/27/14
to Mouhammed Soueidane, killbill...@googlegroups.com
Work has been merged into 0.11.x. Due to API changes, it won't be backported to 0.10.x though.

--
Pierre
Reply all
Reply to author
Forward
0 new messages