Trace order amendments through invoice lines and generate legally compliant invoices

Software improvement 4-In delivery
1

The community has prioritized the «make OFN invoices legally compliant / delivery note» discovery work. Rachel and I have spent the last months iterating on it, discussing with lawyers, etc.
We propose to split the work to be done in multiple features and propose to only move forward with the core feature, the following ones will be reprioritized through the regular wishlist process.

What is the need / problem:

In 2 words: Make info on quantity ordered/delivered/invoiced/voided/paid accurate and ensure legal compliance

  • Jane needs traceability between what she ordered and what she is delivered
  • Mary/Shannon need to be able to issue invoices that are legally compliant in all OFN instances
  • Mary/Shannon need to be able to get accurate data into their accounting package to manage invoicing, including if/when some adjustments happen after invoicing

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. There is no traceability of what happened. If you export data into accounting/invoicing package you won’t have the traceability of what happened either. Also in France invoices need to be sequential and seller should get a dedicated serie for their sequence.
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. Legally data that serve the establishment of legal documents (invoice especially) should be unalterable.

This concern both users who use the OFN invoicing system and users who use external integrated packages.

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 (in France it’s 15€ per invoiced issued that the hubs will have to pay with the current invoice)
  • When there is a difference between what was ordered and delivered it’s not easily communicated and understantable for customers

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

Potential solutions that will solve this problem

We discussed with the devs in Porto around 2 possibilities

1- the possibility to evolve a bit the BOM page and save delivered quantities separately from ordered quantities.

2- the info display on invoices. Whether OFN is integrated by a user with an external invoicing or provide a basic internal tool, we need to be able to extract and share precise data of order amendments, so that the hub can adjust invoices (if they already issued it) or generate an accurate invoice that enable the customer to understand the gap with what was ordered. Two ways to treat the accounting data :

  • 2.1 Each time a modification happens on an order, a new order that cancel and replace the precedent is issued. Through the chained invoices, we can have the traceability. We could even display the events in the last invoices of the chain.

  • 2.2 If something happens after invoice is issued, the hub can generate a complementary credit notes (if credit) or make a compelmentary order (if more quantities) but the original order remains as such.

What came out of discussion with devs:

  • On invoicing, all devs agree that 2.2 is more complicated both technically and in term of UX.
  • On capturing gaps on orders, they all agreed that it is pretty complex and would be great to avoid if we can. We agreed that in a first iteration, we don’t need to capture in a separate entry the delivered data. We can keep on modifying the original invoice, as long as the modification are traced through the invoice lines ! It looks much simpler and seems to meet the needs described above. So 2.1 is the preferred solution.

We came up altogether with the following 4 feature candidates:
FC1: Each time a modification is made to an existing order, we generate automatically an invoice that cancel and replace the precedent and store the PDF in hard.
FC2: We use JSON to replace each time the PDF and generate a new PDF on demand
FC3: We create a simple invoice data structure with order ID, Invoice ID, status, invoice lines (created from line items), timestamp, etc. And invoices are linked with one another when a new invoice is associated to the same order, cancel and replace the precedent. Each time the new order is generated in a PDF
FC4: same as FC3 but each time a new order is generated in a web page (not a PDF)

Given the team in Porto solution FC3 or FC4 (details to agree upon on the form PDF or web page, seems web page would gain) seems to be the most simple and less risky. Avoiding PDF completely and leveraging printing stylesheets would remove a big burden. PDFs tend to consume lots of system resources, but also require quite big dependencies in the app such as wicked_pdf or wkhtmltopdf-binary. So the feature candidate would tend to be FC4.

Precision on the scope

  • We propose in this first scoped feature not to touch at all BOM page, users will use it as is to manage delivered quantities (on a second iteration we would improve the UX of that page). And only focus on fixing the tracing of order modification through invoice lines / invoices.
  • Only the hub manager side is in scope, the customer will see the same from her account. The hub manager will be able to see for a given order the list of invoices generated for that order and if she clicks on “send/print invoice” she would send/print the “up-to-date” invoice, but the precedent one will be available if needs be to trace.
  • We need invoice numbers to differ from order number as multiple invoices can be issued for the same order. Also French accounting rule impose to enable the seller to have a sequential number (and a serie associated, like B101, B102, B103, etc.) so we propose to include in scope the ability for the hub manager to setup for a given hub a serie code and the first number of the sequence, for every single invoice afterwards to follow that serie-sequence. Is there any issue with other countries if we do that? Even if you don’t need it, does it cause any issue?

If we need afterward (other wishlist) to issue a delivery note we will be able to use up-to-date order data which will correspond to the actually delivered goods. Other needs like make invoice accessible from “account section”, or enable easy to use packing support will be in other wishlist to prioritize.

A step further into inception

We listed 3 possible options for how new invoices that cancel and replace the precedent ones are issued:
a- every time a modification is saved, a new invoice is generated (new invoice number that cancel and replace the precedent). That could cause some problem when using BOM if you modify info by products on all orders, saving is automatic so might end up with 10 invoices that cancel and replace the precedent for a same order.
b- the first invoice is automatically generated (when order is complete), and then, modification happens, but a new invoice is generated (with all the gaps captured at once) on demand, if/when the hub click on “print/send invoice”
c- no first invoice is automatically generated, only when the hub manager click on “print/send” invoice. The problem is that with that option, if the first invoice is not generated we loose the traceability as we wouldn’t have the first invoice so no one will cancel and replace the first invoice.

We thought that option b could be a good option to start with.
We could have some checkbox “generate OFN invoices” to enable a hub that doesn’t want to generate any invoice from OFN could check, it would “hide” the invoices section even potentially. But still she would be able to export the data to integrate into accounting package.

T-shirt size of the selected feature candidate

L

Metrics to measure if need is well satisfied after feature has been implemented

  • Lawyers from every instance confirmed that invoices printed from OFN are legally compliant and don’t put users at legal risk
  • More users actually capture delivered data in OFN because they find the process (for export data or internal invoicing) useful (how to measure?)

Feature owners :

Epic and/or project board where you can follow implementation

TBD

Connected wishlist and discovery discussions:

2

Awesome recap @MyriamBoure thank you! I would be happy to be PO on this but maybe it’s best if we re-assigned when we have our priorities?

3

can I check - when we say this will make invoices legally compliant - does that mean this work will also put the supplier names on the invoices (legally required in Canada I believe - buyer has to fully understand what they purchased, and in an on-line market that means understanding whose product it is.)??
I understand if Canada is the only instance that needs this and that makes it out of scope. BUT I think if we are working towards a global instance - that we need to NOT assume our invoices are legally compliant everywhere. To do that, each country (instance with different taxation and accounting requirements) would need to be able to build their own legally compliant invoice template or something.
But besides the legal issue - given transparency is a key guiding principle of OFN - I don’t see why we wouldn’t want to share the producers name with the consumer.

1 Like
4

Agree with @Rachel. Awesome summary. This one wasn’t easy at all.

Regarding feature candidates, It’d like to highlight FC4. Avoiding PDF completely and leveraging printing stylesheets would remove a big burden. PDFs tend to consume lots of system resources, but also require quite big dependencies in the app such as wicked_pdf or wkhtmltopdf-binary.

1 Like
5

@tschumilas I woudl treat both things separatly, adding the supplier name is a super tiny thing that could for me go straightforward to dev… this feature is much bigger and more on some core processes behind invoicing, not linked to the content of the invoice info really. So please vote on Add supplier name into default invoice template ! I’ll be happy to support that we move it quickly to the pipe, I think it’s XS feature we just need to check with a dev, let’s discuss there please :slight_smile:

6

Cool @sauloperez I added your comment in main post :slight_smile: Would like to hear others feedback of course on this and see if the feature candidate we propose get some consent? @Kirsten @lin_d_hop @Theodore @lauriewayne1 etc.

7

I agree that b sounds like the best option for the problem stated. Happy for the work to go ahead.

To sanity check, the modifications history will not be captured for an order at all unless the user generates an invoice?

I know I am late to the party so I’m sure this has been discussed at length already and thus sorry for throwing a spanner in and I hope it doesn’t create complications…

To my mind I feel like there might be benefit in having all modification data stored, rather than overwriting the original order data - so there is orders data and a modification data. Then invoices are generated as a snapshot of the current state of the order, including up to date modifications.

This is a common ecommerce problem. I do wonder how spree handles order modifications?
@sauloperez @luisramos0 @maikel @Matt-Yorkley

8

As a first iteration, this is how will keep track of the modifications. So, we already provide a solution while being legally compliant. Then, in an upcoming iteration we can think of not modifying the order.

This is a common ecommerce problem. I do wonder how spree handles order modifications?

I don’t recall Spree doing anything about it at least in the 2 series, I can’t tell about future versions.

2 Likes
9

Thanks Pau. Like I say I’m happy with the solution and don’t want to change anything. Just engaging a little. Totally trust you folk :slight_smile:

1 Like
10

Nice doc Myriam!
I vote FC4 option b to start with.
My estimate is L.

11

should we check future spree? assuming we’ll go there eventually?

1 Like
12

Print stylesheets are definitely the way to go. We’ve used that system for CLFC for years now, and when we run the invoices, load the HTML page and save it. In Chrome, that gives you a ‘save as PDF’ option that takes that workload off the server. It’s very flexible and lightweight.

1 Like
13

I think we asked the devs in Port and it doesn’t seem Spree did something on that direction… check with @sauloperez and @luisramos0 can one of you confirm ?

14

sorry, I have no clue about invoices in the future spree, would have to investigate.

15

I haven’t investigated that either but it’s on the list.

16

there are plugins for invoicing but only in spree 3:


17

So :slight_smile: The time has come to prepare this one to get it github ready :slight_smile:

Here is a recap of the chosen solution:

  • Each time a modification happens on an order, a new order that cancel and replace the precedent is issued. The new one would contain all info (last state + history of changes)
  • We create a simple invoice data structure with order ID, Invoice ID, status, invoice lines (created from line items), timestamp, etc. And invoices are linked with one another when a new invoice is associated to the same order, cancel and replace the precedent.
  • Each time the new order is generated in a web page (not a PDF).

Now that I’m diving again on this solution, I have a few questions/comments:

  • On the list of orders, do we need to show a link between the previous order and the new one? the previous one will be cancelled. I wonder if it wouldn’t be easier to remove cancelled orders from default completed orders, to avoid a large list of completed orders that you cannot print with a single “select all action”. Anyway that’s a design question, but maybe I don’t recall properly what we mean by creating a new order. So I would like a confirmation that this solution will indeed generate a new line of order in /admin/orders?q[s]=completed_at+desc as a final result
  • Both orders will need to have the same number. Is this possible in the current OFN model?
  • In product curation we decided to release separately order amendments and invoice numbering system. Is that still a valid idea or would the solution benefit from a new numbering system right away?
  • We create a simple invoice data structure with order ID, Invoice ID, status, invoice lines (created from line items), timestamp, etc => is everyone clear on what the “etc” means?
  • invoice generated will not be in PDF anymore. What are the implications on the current bulk invoice PDF: we stop supporting it and instead develop a new bulk printing option within this work?

Thoughts? @luisramos0 @sauloperez

18

Maybe I miss the last conversations about this topic? I cant remember agreeing on cancelling the previous order. In my mind the agreed solution was to cancel the previous invoice, not the order, and issue a new invoice with the latest data on the order.

Is there a tech lead assigned to this already? I think we need a dev to look at this again with more detail now.

Another point is that although at the time I think we were thinking about having an invoice structure that would hold history (line items, etc), since then we also agreed we need some form of edit trail on the order. I think an edit trail on the order will be useful to build the invoices as the invoices can be associated to a specific version of the order. We need to decide what’s the way forward…

19

@luisramos0 actually it’s maybe me who got confused reading the notes. I was reading through the comment that we would go to option c (no first invoice automatically generated) and then I didn’t see how we could cancel something that wasn’t generated before. I believe that’s where I ended up believing we would cancel the order, I’m sorry.
But now re-reading again I see that you were in favor of option b (only the first invoice is automatically generated) which makes more sense and allows cancellation of the invoice.

Not yet. Would you be interested in that role?

Yes aligned. But the invoice would still need to reflect the trail to be compliant. But that sounds like a more clear path forward.

20

ok :+1:
yeah, I can be the tech lead on this one :+1:

I see this is next up in the priorities after T&Cs. I’ll schedule some time this week to go through the details. I’ll post results here. We can then see if we need a call. ok?