Adjustments about billy HOT 12 OPEN

@mbr - we've got a couple of enhancements we want to make to billy in order to get it ready to process invoices for Balanced. Can you work with @victorlin on this one? It may be that we can simple add an item to the invoice but the UI on the dashboard requires them to be grouped separately from other invoices when displayed.

from billy.

@mjallday

I am not pretty quite understand the scenarios for adjusting an issued invoice, could you give me some examples?

So, adjustments are only allowed to be made when an invoice was failed? Or even when it was done?

from billy.

This is an invoice generated by Balanced currently. We need to be able to replicate this functionality.

from billy.

a common request is that we should simulate invoices in test environments too

from billy.

Some thoughts about fields in an item

• Type -> type field, the type of this item
• Quantity -> quantity field, quantity of this item
• Transaction amount -> amount field, total amount of processed transaction, althought this is not common in most applications, as we need this, we should meet our need first, so just add it anyway
• Fee -> name field, the Fee is actually a description field, so a name field for common description would be fine
• Total -> total amount to charge

from billy.

@victorlin:

• why not call type, event_type - since billy will just be listening for interesting events and aggregating right?

all the others look good!

from billy.

@mahmoudimus
Because I want to make Billy meets common usage scenarios as much as possible, type is more common than even_type IMHO.

from billy.

I am think about some special cases for invoice adjustment. Say, we own a guy John 100 cents, so there is an adjustment -100 should be applied to the latest invoice. But what if John's latest invoice has only 50 cents in total. By applying -100 cents to 50, we still own John 50 cents.

In my opinion, it's better to leave this kind of logic to user rather than build them into Billy. Which means we only allow user creating valid invoices with adjustment (the total cents should be grater than 50). Otherwise it would be a little bit complex to handle these zero amount or even negative amount invoices.

from billy.

Currently in the case outlined above Balanced will generate an invoice for a with a $0 total and decrement the amount owed to the customer. Balanced will continue to do this until the balance has been used up and then generate invoices as normal.

I'm not sure if this is optimal or should be handled by Billy.

from billy.

@victorlin in my opinion, @mjallday has the Principle of Least Surprise solution. While Billy should be configurable and customizable, we're ultimately trying to build the best product -- so we should keep in mind sensible defaults.

Fwiw, this is also the most common solution to this problem from other providers.

from billy.

So was there a consensus reached on what to do?

from billy.

@mbr i think the first step is to implement an MVP it so that it satisfies the requirements for Balanced's invoices. we can extend it from there.

• extending the items collection to be type quantity unit amount description total
• ensure we can create invoices with a total amount of $0.00

I believe that's all we need for now. It will become clearer once we get #72 in place since we will be able to see create some integration tests with actual balanced invoice data.

from billy.