Adjustments

[mjallday]

Often at Balanced, we need to make ad-hoc adjustments to invoices.

This can be done as part of an initial creation of an invoice or after an invoice has failed and is about to be resubmitted.

An adjustment can be for any arbitrary amount, both positive or negative and will have a string field associated with it describing the reason for the adjustment.

Can Billy handle this?

[mjallday]

@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.

[fangpenlin]

@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?

[mjallday]

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

[mahmoudimus]

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

[fangpenlin]

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

[mahmoudimus]

@victorlin:

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

all the others look good!

[fangpenlin]

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

[fangpenlin]

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.

[mjallday]

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.

[mahmoudimus]

@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.

[mbr]

So was there a consensus reached on what to do?

[mjallday]

@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.