Make info on quantity ordered/delivered/invoiced/voided/paid accurate and improve packing operation efficiency

[This is a proposal to replace to current prioritized icebox Make OFN invoices legally compliant as we are trying to be more precise about the need and scope we propose to cover. So putting it pack as draft to make sure we all agree on this phrasing and scoping before moving forward again.]

What is the need / problem

There is a higher level of need and a lower level of need which cover the scope of the present icebox.

Let’s remind the higher level of need to contextualize this icebox.
The higher need is a pretty general need to make processing of orders easy for the hub manager, accurate all along the process and legally compliant (from complete saved orders to collection by customer, including ordering products to suppliers, preparing the baskets, ship them, invoice and collect payment).
This higher level of needs comes from 3 mains issues identified in the previous icebox and recent associated discussions:
a- Today invoices that can be generated from OFN are illegal as it is possible, if you amend an original order, to print two invoices with the same number and different content. To make invoices legally compliant we need to be able to capture what is delivered separately from what was ordered and invoice what was delivered, given sales contract.
b- Because of that also today Jane can be very confused as there is no consistency and no simple way to reconcile what was ordered with what is invoiced. Jane gets pretty confused, she has ordered something, is delivered something else but has no trace of what she had ordered and the differences (which is logical because today we change original order information, so we loose it). Legally data that serve the establishment of legal documents (invoice especially) should be unalterable.
c- Also today there is no simple support/tool to pack and prepare the baskets, hubs need to use the current exports but some hubs needs are not met so they spend quite a lot of time reformatting, crossing info to fill in gaps, etc. and sometimes just can’t use the OFN as they don’t get the info they need to operate.

We tried to visually summarize the order life cycle on those two slides to make the process clearer (Note that the status displayed here are not exactly how they are implemented today in Spree. I didn’t put the invoice step in this flowchart but should be prior or synchronous with any payment, and payment can happens at different stage, I have not found yet how to display it properly.)

The scoped unmet need that we propose to prioritize:

To make information accurate within the OFN all along the process between quantities ordered, delivered, and invoiced thus paid, make packing operation easier by enabling the hub manager to easily see what needs to be put in baskets and capture eventual gaps, and enable clarity for Jane by providing a delivery note that can be reconciled with the invoice and eventual credits/voids.

This unmet need as you see covers the 3 pain points identified above and thus partially covers the bigger need to a frictionless end to end process.

Who does it impact?

  • All hubs generating invoices from within OFN (Mary and Shannon) or reusing data for their invoicing/accounting packages
  • Jane as until now it is not easy for her to understand the changes between ordered and delivered

What is the current impact of this problem

  • Invoices generated from within OFN are not legally compliant so it makes hubs at risks legally speaking
  • When there is a difference between what was ordered and delivered it’s not easily communicated and understantable for customers
  • Hubs manager find it hard to organize packing and capture gaps, they don’t know how to capture them and operate the relevant operations on orders

What is the benefit in focusing on this

  • Improve the hubs ability to be legally compliant
  • Improve customers understanding of their billing
  • Improve efficiency of hubs when packing baskets and taking the relevant actions if quantities are missing

Links to more details

Potential solutions that will solve this problem

1- Implement a new “packing support” feature + the ability to issue refundable credits/voids for a given order

>>> The packing support feature will:

  • Make it easier to prepare the baskets and capture gaps in delivered quantities if there are
  • Enable to issue one “delivery note” per order that can be sent alongside the basket to enable Jane to understand what she gets and will have to pay compared to what she ordered.

In real life, there can be one delivery note covering multiple orders (if two orders are delivered in one shipping) OR there can be multiple delivery notes covering one order (if an order is delivered in multiple shipping). For simplicity and learning process we propose in the scope of what is prioritized to limit to the one-to-one case: for one order there is one delivery. If multiple deliveries happen, a complementary order will be made by admin to reflect the missing items that remain to deliver. If a delivery covers multiple orders, one delivery note per order will be created.

We were wondering with @Rachel if we couldn’t use existing “adjustments” possibilities in Spree, especially in latest version of Spree. Today an adjustment can only be an amount deduced/added to the order total. But in Spree 2.2 “you are able to retrieve the specific adjustments of an Order, a Line Item or a Shipment.”. We would like actually to retrieve an adjustment based on quantity (amount can be deduced) from a line item, so that seems like a possible way to tackle this. It seems logical that gaps in delivered quantities are treated as adjustments on the order, it doesn’t modify the original order.
So that “packing support tool” would actually be a bulk action capturing at once multiple adjustments for various line items of various orders.

>>> The ability to issue refundable credits/voids for a given order will enable both the hub manager and Jane to reconcile the information about what was ordered, delivered, invoiced/void and paid.

The invoicing operation is complex. We are paying some consultancy from lawyers in France to clearly understand the legal aspects and make sure that we build a meaningful process. Technically the invoicing context depends on the sales contract. Sometimes as a customer you will be invoiced at the time of ordering, and will be asked to pay before having received the products (technically that’s what happens today when a hub uses a Stripe payment method, even if implicit… as money is transferred on hub account immediately). Sometimes as a customer you will receive the invoice and have to pay only after the products are delivered. So it seems invoicing and payment can happen at any time in the process, and the treatment of gaps in deliveries will depend on it (ex: is Stripe payment at ordering time, refund will have to happen). So to take it simple as a first step, and don’t touch our invoicing process, we propose to work on a way to issue a refundable credit/void. “Refundable” means that we don’t include in scope here the fact that a credit/void can be used to pay another order.

When discussing with @Rachel we found two possible directions to do this:

  • Modify somehow the “print invoice gem” we are using so that adjustments captured after invoice have been printed are not added, the invoice is locked while issued. And add then a similar type of tool to enable to “print void”, with some predefined void template reflecting the eventual adjustments.
  • Or use only the current “print invoice” gem but store each invoice generated under a unique number, and make sure if a new adjustment is made, the new invoice issued mention that it “cancels and replaces the precedent one number #xxx” with some incremental numbering. That option was investigated and mockup up here slides 2 to 4.

Both options seems legally valid, we need to see what is the easiest with how OFN works today.

2- Any other idea? (we are planning a session with devs in Porto to make sure we don’t see another simpler way to cover the need, if you have ideas please share)

Value x ease analysis and selection of our feature candidate

To be done with devs in the Porto session (if more than one option appears…)

Metrics to measure if need is well satisfied after feature has been implemented (to be discussed)

  • Hub manager can capture gaps on delivery (Y/N)
  • Given user surveys, hub managers have the impression that packing support feature makes their packing operation simpler.
  • A delivery note can be issued and has accurate info of ordered vs delivered (Y/N)
  • A credit/void can be issued and has all the necessary info on it for Jane to be clear with what she paid (Y/N)

Epic and/or project board where you can follow implementation

To be done later on.
(Previous epics - we need to decide what to do about them, if we close and open new ones to clean up or if we just update them. In any case we need only one epic

  • Modify somehow the “print invoice gem” we are using so that adjustments captured after invoice have been printed are not added, the invoice is locked while issued. And add then a similar type of tool to enable to “print void”, with some predefined void template reflecting the eventual adjustments.

I’m not sure I follow. Does this mean that after issuing the invoice the user can’t issue any new one? Sorry for my ignorance but what would a “void” display?


  • Or use only the current “print invoice” gem but store each invoice generated under a unique number, and make sure if a new adjustment is made, the new invoice issued mention that it “cancels and replaces the precedent one number #xxx” with some incremental numbering. That option was investigated and mockup up here slides 2 to 4.

Is there really the need for a history of invoices? and I wonder, do we allow editing orders no matter the state the order is in?

What I see is that we’re widening the scope of the feature, adding lots of cases and scenarios, and it’s not clear to me whether they serve a need or not.

@sauloperez the thing is: we need a way to reconcile the info between the invoice, and the delivery note.
I take one concrete simple real life case: a hub collect payment through Stripe at order.
When preparing the order, some products are missing, so delivery note show something different.

Then what happens? We need a way to loop, else the customer has an invoice saying “you have 100 to pay” and a delivery note saying “we delivered the products for 80”… we have two way “accounting speaking” to do it:
1- either we edit a new invoice that cancels and replaces the precedent but then we need to store the previous versions and increment the invoice number (see proposal above)
2- either we don’t touch the invoice (so yes, we cannot print another invoice after printing a first one) but issue a credit note (void). A credit note is a separate document, referring to a given invoice number.
Examples in French: and English: and see example image below

So as we have an invoice template, we can have a credit note template and issue a PDF the same way we issue the invoice PDF.

We can’t just leave the user with two documents that are unconsistent (the invoice, and the delivery note) as part of the need is to reduce confusion for Jane… isn’t it? If you have other ideas on how we could ensure that both documents can be reconciled and Jane is clear with what she is paying, please suggest!

Am I correct in stating that this problem with keeping a history of invoice modifications, is only a problem when payment has been made before the goods are delivered/picked up? Correct? Because if someone is paying in person at a hub or paying at delivery - then they are presented with their invoice (the one and only invoice) at the hub. In these ‘pay at pickup’ and ‘pay at delivery’ situations - the hub/shop manager has already reconcilled what was ordered and what was delivered. So - the customer received an ‘order confirmation’ - which basically just confirms what they are wishing for. Then their order is reconciled based on what was actually delivered by the suppliers to the hub. Then the buyer receives an invoice for what they owe. the hub manager has already made any changes to it before the customer gets it. its a ‘working copy’ until the customer gets it and pays it.

So the problem is with advance payment - right?

maybe this is obvious - but I’m thinking about UX here. We are bulding a very very complicated system - that will be used by, I suspect, a small number of users. I totally agree we have to do it - esp if we want larger more sophisticated users - but in the process of doing this, we are also making things really really complex for our ‘simple hub’ users - who just do payment at pickup. Too bad. Is it possible to imagine two options in the platform - option a for simple ‘pay at pickup’ or ‘pay at delivery’ hubs, and option b for pay in advance hubs.

It’s pretty true, if hubs don’t print invoices to do the packing :wink: Because if we don’t block issuing invoices before packing is done, they could theoretically still do it. We could potentially disable invoice printing for orders before they are packed BUT as you say if the order is paid when placing order then the invoice needs to be sent at that moment, and then amended somehow if there are gaps, so it might be hard to block invoicing and we anyway need the possibility to amend invoices.

Also anyway, you can have some broken products when delivery happen, so other amendments later on that will need either a credit note or cancel and replace the previous invoice, so we need anyway to choose a process between the two options.

I don’t think it’s complex @tschumilas, being able to issue a credit note is pretty basic feature (the other option about cancelling and replacing invoices is just another implementation option so we can see which one is the easiest to implement), and in UK and Aus it seems lots of hubs are taking payments through Stripe…

NB: I just end up a call with a big cooperative and multi buying group project in Sicily, using Open Food France instance, and they definitely need this feature too, we just discussed it.

And just to complicate things further, CLFC does a bit of both every week. A lot of our members pay before pickup via EMT after getting their invoice that morning. Others pay at pickup by cheque or cash. So a one or the other approach wouldn’t work well in our case.

We’re also one that (currently) uses invoices to do the packing. But since OFN invoices don’t currently show the producer for each product, that wouldn’t be an option for us.

Also under the heading of legal compliance, the producer must be listed on the invoice as well - since we are legally considered a ‘farm-to-tailgate’ the products must be shown as coming from the producer, NOT us. We’re technically a marketing and distribution company. If we sold products directly, we’d be considered retail, and a completely different set of laws would apply … and shut us down.

I think a version numbering system on invoices would be a good solution. IE: Invoice #10001R0. R for revision, 0 for original. If there is a change, the invoice number itself remains the same, the revision number increases. So, #10001R1, #10001R2, etc. Ties back to the original, tracks changes to maintain compliance. No need for voiding, etc. But it could be much less simple on the backend than it sounds like to just say the idea. All the logic and DB linking and such gets pretty crazy in code when it sounds so simple. :slight_smile:

Thank you for those order cycle slides @MyriamBoure. For a ‘summary,’ they’re still plenty complex!!

And just to complicate things further, CLFC does a bit of both every week. A lot of our members pay before pickup via EMT after getting their invoice that morning. Others pay at pickup by cheque or cash. So a one or the other approach wouldn’t work well in our case.

I think what we propose

does work for both cases @CLFC. A hub could decide to issue an invoice before the pickup for the people who pay before, and others could pay “on site”, it doesn’t really matter as long as IF there is a discrepency, they can void or issue a refundable credit note. We propose that as a first step as it is the easier way to support any behavior from hubs and give a lot of flexibility. We will check with devs in implementation is simpler with invoice numbering or void. But if you have cases where users pay before getting their product you might have to void/issue refundable credit, as you will have money going out so you need an accounting document for that…

About comment on issues, it’s exactly what I was commenting in some other discussion, technically you need one invoice per producer as they are the “transaction holder”, you are just a sales facilitator, so to be honest I don’t even think the current invoice with the farmers name would answer the need. I guess you need some form of invoice which technically is an aggregate of invoices from each producer, right? Maybe that’s ok for you to have just one invoice in the name of your hub if you have the producer name below each product… but I doubt it. You sell services to the producers so you invoice to the producers your services. (check this discussion to understand more what I mean and please let’s discuss there on that specific topic which is not the topic discussed here!)

The producer name on the customer invoice IS sufficient for our needs. I’ve already created a script that takes an OFN report and produces “producer invoices” for us. We need this separate step regardless, as it is where we will calculate our producer fees. We provide the invoice with payment as a record of their sales, the fees we collect, as well as the payment we issue to the producer.

As far as discrepancies/corrections go, there are several ways it could be done, and ultimately they’ll all work. I would definitely see what the devs say on the subject, since they will have a better grasp on the implications of different methods behind the scenes. Let’s see what they come up with.

Closing this issue as cancelled and replaced by Trace order amendments through invoice lines and generate legally compliant invoices which goes more into details in analysis on solution and proposed feature candidate to start with. The “hub can easily generate packing slip” wishlist remains as such then, separatly from this post.
Other smaller wishlist on specific parts of that discussion will be open separately to be moved forward on their own, small feature by small feature.