- Checkout is complete. The supplier needs a purchase order.
- If each document is assembled independently, the same transaction quickly develops several versions of the truth.
- One file uses the marketplace order number while another invents its own reference.
- This was the client problem we addressed in a multi-vendor procurement platform built on Medusa.
The client problem
Checkout is complete. The supplier needs a purchase order. The warehouse needs a packing slip. The receiving team needs a receipt of goods. Accounts payable expects an invoice, and a later return may require a credit note.
If each document is assembled independently, the same transaction quickly develops several versions of the truth.
One file uses the marketplace order number while another invents its own reference. A packing slip includes products from the wrong supplier. A purchase order shows a return label as the original delivery method. A regenerated PDF quietly adopts today's product description instead of what was actually ordered.
This was the client problem we addressed in a multi-vendor procurement platform built on Medusa. We created a connected document family around the order: purchase orders, packing slips, receipts of goods, invoices, receipts and credit notes. Each document has its own purpose and lifecycle, but all of them begin from governed order and seller context.
The goal was not to generate more PDFs. It was to make every document recognisably part of the same commercial event.
Procurement continues after checkout
A conventional storefront can often stop at an order confirmation email. Procurement cannot.
The buyer may need a purchase order before the supplier begins work. The warehouse needs a list of what to pack. The property receiving the goods needs to record what arrived. Accounting needs an invoice that can be matched to the order and receipt. If goods come back or an invoice changes, the correction needs its own identity.
Those audiences ask different questions:
- What did the buyer authorise?
- What should this supplier ship?
- What did the property receive?
- What amount should accounting review?
- Which later document corrected the original?
Using one generic “order PDF” for every purpose hides these distinctions. Building unrelated generators creates duplication and drift.
We modelled each document type explicitly while keeping its relationship to the order and seller visible. That lets the platform preserve one chain of references without pretending that a purchase order and an invoice mean the same thing.
Build documents from the seller's part of the order
In a multi-vendor marketplace, one buyer checkout can produce commerce activity for several suppliers.
A supplier document must therefore be seller-scoped. The generator cannot simply iterate over every line attached to a parent purchase and assume it all belongs on one PO or packing slip.
The document workflows receive both an order and a seller identity. Seller-order links and seller-owned product or shipping relationships determine which information belongs to that document. Purchase-order delivery methods are filtered to the supplier's shipping options, and return shipping methods are excluded from the original purchase-order representation.
This produces a practical result: seller A receives a document for seller A's commitment, not an accidental view of seller B's products or delivery arrangements.
The same scope also gives each supplier control over its document presentation and sequence while the buyer can still retrieve the complete family from the order context.
Multi-vendor checkout remains one buyer experience. Document generation respects the operational split that follows it.
Give every document a durable identity
The document module stores purchase orders, packing slips, receipts of goods, receipts and invoices as records, not transient download responses.
Each record connects a document number, display number, seller, order and generated PDF. Packing slips and invoices may additionally refer to a fulfilment; invoices can refer to a return when representing a credit note. Database uniqueness rules prevent the same active seller/order/document scope from quietly multiplying.
This durable identity supports two important behaviours.
First, a user can return later and retrieve the same document rather than generating a new interpretation on every download. Second, the system can link related corrections and replacements without overwriting the identity of the original.
The generator workflow follows a get-or-create pattern. It creates and safely links a missing document, or reuses the existing one when that business document already exists.
That sounds like a small implementation choice. Operationally, it is the difference between “download the purchase order” and “produce another file that happens to say purchase order”.
Keep one recognisable order reference
Document numbers need to be unique, but they should also help people recognise the transaction.
The platform derives document display numbers from the Medusa order display number plus the document type and its sequence. A PO, receipt of goods and credit note can therefore carry distinct identities while retaining the order reference that joins the chain.
For example, the numbering utilities can form type-specific references such as PO-[order]-[sequence] and ROG-[order]-[sequence]. Invoices retain the canonical order number where that is the required accounting reference.
This makes reconciliation easier for humans and integrations. A supplier can quote the PO number, a receiving team can identify the related ROG and accounting can trace both back to the same order.
The important rule is not one universal formatting convention. It is that numbering is deterministic, seller-aware where required and anchored in the commerce record rather than generated independently inside each template.
Snapshot history instead of rewriting it
Commerce data changes.
A product title, image, SKU presentation or dimension may be corrected after an order. A shipping method can change during an operational exception. A seller may upload a new logo or update its address. If an old PDF is regenerated entirely from current data, it can cease to represent the transaction at the time it occurred.
For purchase orders, an already generated PDF is reused rather than rebuilt from later order changes. Focused tests protect this snapshot behaviour. The document keeps its existing file identity even when the order object supplied later contains replacement item data.
Other document changes use explicit lifecycle paths. Invoice replacement has its own record. A credit note can be tied to a return. Claim and return workflows can create changed commercial states without pretending the original document never existed.
This does not mean every document is frozen at order creation. Some are generated later from the then-valid operational state. The rule is more precise: once a historical document has been generated, later mutations should not silently rewrite what that document said.
Preserve product identity at the moment it matters
A useful procurement document needs more than a product title and quantity.
Buyers and warehouses may rely on SKU, variant details and physical dimensions. Those values affect recognition, packing, receiving and downstream reconciliation. If a generator resolves them inconsistently, two documents from the same order can describe the item differently.
The document utilities use order-line and product information to derive a stable document SKU and retain the relevant product representation. Tests cover document SKU selection and order-line dimension handling so a later catalogue edit does not casually replace the historical order context.
This is particularly important for supplier catalogues. A seller may update its source feed after an order, but the property still needs to know which item was authorised and delivered in the earlier transaction.
The order is therefore not treated as a pointer to “whatever the catalogue says now”. It carries the commercial snapshot from which the document family can explain the purchase.
Let suppliers configure presentation without changing truth
Suppliers need their own identity on operational documents.
The document settings model supports seller-specific addresses, logos and presentation settings. Invoice and packing-slip settings can evolve independently where their use cases differ. The PDF generator applies those settings to a controlled template rather than allowing every supplier to redefine the underlying commercial data.
That separation is valuable.
Branding answers “who issued this document?” The order context answers “what transaction does it represent?” A logo update should not change quantities. A template choice should not change the order number. A seller address should come from the correct configured source rather than an unrelated buyer address.
Tests cover preservation of invoice settings and selection of the header address. The platform can therefore give suppliers a recognisable document while retaining a consistent marketplace contract.
This is another reason an extensible Medusa foundation matters: presentation can be customised at the seller boundary without forking the entire order lifecycle.
Make delivery documents reflect fulfilment
Packing slips and receipts of goods answer different questions.
The packing slip describes what the supplier is sending, potentially for a specific fulfilment. The receipt of goods records the receiving side of the process. Neither should be inferred merely from the original requested quantity when fulfilment or claims have changed the operational picture.
The document records therefore retain order and seller identity, and packing slips can additionally bind to a fulfilment. That allows the marketplace to represent partial operational events without issuing one ambiguous file for the entire order.
Purchase orders include the applicable outbound shipping method. The generator deliberately ignores methods connected to a return and filters methods by seller. Tests cover a normal seller delivery, multiple allowed methods, missing data and exclusion of a return label.
The business benefit is clarity at handoff. The supplier, carrier-facing operation and receiving property see documents shaped for the actual movement they are handling, while their references still join the original purchase.
Treat corrections as new facts
Returns, claims and invoice corrections should not erase history.
When a later event changes the financial or physical outcome, the platform can issue a related document: a credit note for a return, an invoice replacement for a corrected source or a receipt reflecting the relevant fulfilment state.
The original remains identifiable. The correction records why the document family changed.
This is much safer than overwriting an invoice PDF in place. An accountant who downloaded the first version can understand why a second file exists. An operator can connect the return or replacement to the document it affected. A supplier cannot accidentally make yesterday's purchase order adopt today's operational exception.
The exact regeneration policy differs by document type because their meanings differ. Historical snapshots are reused; replacement paths are explicit; documents not yet generated use the current governed state appropriate to their lifecycle moment.
One blanket “always regenerate” rule would be simpler to code and harder to trust.
Why Medusa was the right foundation
Medusa already held the commercial backbone: customers, sellers, orders, line items, fulfilments, shipping methods, returns and payments.
We extended that backbone with a document domain designed for the client's procurement journey. Dedicated workflows create and link the appropriate document. Seller scope selects the operational slice. Settings control presentation. Order-derived numbering connects the family. Historical files and explicit replacements preserve the sequence of events.
On a rigid ecommerce platform, this often becomes a patchwork of template plugins and external document services, each reconstructing the transaction differently. The resulting integration effort is not only about PDF rendering; it is about recovering order truth after the platform has lost the business context.
Medusa let us keep document generation close to the entities and workflows that already knew what happened.
That architectural choice produced a business capability: one extensible commerce engine could support the full procurement trail instead of stopping at checkout.
A practical procurement-document checklist
Before generating documents from a marketplace order, define:
- Which document types have distinct business meanings?
- Is every document scoped to the correct seller?
- Can a packing slip or invoice belong to a specific fulfilment?
- How does each display number retain the canonical order reference?
- Which product and line-item fields must be historical snapshots?
- Are seller-specific shipping methods selected correctly?
- Are return shipping methods excluded from the original PO?
- Which logo, address and template settings belong to each seller?
- Does a repeated download reuse the existing historical file?
- Which later changes require a replacement or credit note?
- Can buyers, suppliers and accounting retrieve the related family from the order?
- Are document creation and order linking safe to retry?
These questions turn document generation from a template task into a procurement design decision.
The broader lesson
The client did not need six unrelated PDF buttons.
They needed every operational team to recognise the same purchase while seeing the document appropriate to its responsibility.
We used Medusa's order and fulfilment context as the commercial foundation, then added seller-scoped document records, stable numbering, configurable presentation and historical snapshot rules. Corrections became related facts instead of silent rewrites.
The result is a document trail that follows the business: authorised, packed, received, invoiced, paid or corrected—without losing the order that connects it all.