[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
- Legal conformity: what we need to do (A - 1)
- Process improvement from order to invoice
- Suppliers can easily invoice resellers for what they deliver 1
- Hubs can easily generate packing slips
- Inception session: delivery note
- Previous icebox item we have iterated on
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
’ Delivery note · Issue #2230 · openfoodfoundation/openfoodnetwork · GitHub
’ A delivery note can be issued from an existing order · Issue #144 · openfoodfoundation/wishlist · GitHub)
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.