- A buyer completes a large procurement order and chooses a purchase order instead of a card.
- The checkout can accept that choice in a single click.
- A PO may need a reference, buyer confirmation, supplier validation, invoice reconciliation and eventual capture.
- Treating that journey as “payment successful” at checkout would make the interface look simple by making the order state false.
The client problem
A buyer completes a large procurement order and chooses a purchase order instead of a card.
The checkout can accept that choice in a single click. The financial reality cannot.
A PO may need a reference, buyer confirmation, supplier validation, invoice reconciliation and eventual capture. The goods can move before cash does. In a multi-vendor marketplace, one buyer checkout may also become several seller orders, each of which must preserve the right payment responsibility.
Treating that journey as “payment successful” at checkout would make the interface look simple by making the order state false.
For a B2B procurement platform built on Medusa, we implemented purchase-order payment as its own provider and lifecycle. The buyer can use account terms inside the familiar checkout, while the platform keeps creation, validation, payment confirmation and capture as separate business moments.
The client needed commerce on account
Consumer checkout assumes that payment and order creation happen close together. A card is authorised, the order is placed and capture follows a familiar provider lifecycle.
Procurement buyers often work differently.
An organisation may buy against an approved supplier account. The PO proves purchasing authority, not that money has already arrived. A buyer, property or finance team may later confirm payment. The supplier may validate the documentation and capture the payment state only when the commercial conditions are satisfied.
Forcing that process through a card-shaped status creates ambiguity:
- Does “authorised” mean the PO exists or the supplier accepted it?
- Does “paid” mean the buyer says payment was sent or the vendor confirmed receipt?
- Can a seller capture before validation?
- What happens when one checkout splits into several seller orders?
- How does a return change the amount still represented by the PO?
The solution was not a new label on a manual payment method. It was a payment contract that understood account terms.
Give purchase orders a real provider boundary
Medusa already provides the payment-provider abstraction used by checkout and order payment collections. We extended that boundary with a dedicated purchase-order provider.
This lets checkout create a PO payment session through the same commerce architecture as other methods while retaining PO-specific semantics. The order can identify its payment type as purchase order rather than pretending to be prepaid or instant.
The provider boundary matters because payment methods are behaviour, not decoration.
A card integration talks to an external processor. A purchase order coordinates documentary and human decisions. Both need sessions and state transitions, but their definition of progress differs.
By modelling PO explicitly, the UI, workflows and audit trail can use the right words. The platform knows that accepting the method at checkout is the beginning of a financial process, not proof of settlement.
Preserve the payment choice when the checkout splits
In this marketplace, one buyer checkout can contain products from several sellers and stock-owning locations. Completing it can create multiple downstream orders.
That split must not erase the original payment contract.
The purchase-order type and payment state travel into the seller-order context. Each seller can then see that the order is on account and follow the appropriate validation and capture journey. The buyer retains one coherent purchasing experience even though fulfilment and supplier responsibility separate behind the scenes.
This is a subtle but important requirement. If the parent cart knows “PO” but a child order falls back to a generic payment state, operators will improvise. Some will treat it as paid, others as pending and finance will reconcile the difference manually.
Payment type is therefore part of the business context preserved during order creation, alongside seller, shipping and allocation decisions.
Separate four moments that look like one button
The cleanest way to understand the PO lifecycle is to separate its transitions.
First, the buyer selects purchase order during checkout. The platform creates the payment session and records the order with the appropriate payment type.
Second, the PO is validated. This confirms that the order and its purchase-order requirements are acceptable. It does not mean cash has arrived.
Third, the buyer-side payment confirmation can record that the paying organisation has taken its required action.
Fourth, vendor capture records the supplier-side financial completion through the Medusa payment collection.
Those moments can happen at different times and may involve different people. Combining them into one status would remove information precisely where B2B operations need it most.
The implementation therefore uses separate workflows and timestamps. Events can notify other parts of the platform when validation or buyer confirmation occurs, while capture remains guarded by its own preconditions.
Validation is not capture
One of the most dangerous shortcuts would be to allow a validated PO to be captured immediately merely because both states sound positive.
Validation answers whether the purchase-order process is acceptable. Capture answers whether the payment collection can move to its captured state. They are not synonyms.
The capture workflow checks the order before proceeding. Tests explicitly guard against capture when the PO has only reached validation but not the required payment confirmation. Additional guards protect integration-specific confirmation paths from bypassing that lifecycle.
This removes a class of financial ambiguity from operator judgement. The vendor interface cannot simply present every positive-looking PO as ready to capture.
The broader rule is reusable: when a business payment has documentary, buyer and supplier stages, model each stage. Do not compress them to fit a consumer checkout vocabulary.
Keep buyer and vendor responsibilities visible
A purchase order crosses organisational boundaries.
The buyer creates the commitment and may later confirm that payment has been issued through the organisation's process. The supplier validates the order and ultimately records capture. Marketplace administrators may need visibility without impersonating either side.
Separate buyer and vendor routes make those responsibilities explicit. The buyer does not call the vendor capture action. The vendor does not rewrite the buyer's confirmation timestamp. Each transition has a named workflow and can emit the event appropriate to its role.
This is more than access control. It makes the operational story understandable.
When finance asks why an order is not captured, the platform can distinguish missing validation from missing buyer confirmation. When a vendor sees a confirmed order, that state has a business meaning rather than being a generic boolean changed by an unknown actor.
Good B2B architecture makes responsibility legible in the data model.
Let documents and payment state reinforce each other
The platform also generates purchase-order documents from the order context. That document is part of the commercial evidence, but it should not independently decide payment status.
The order and payment collection own the lifecycle. The generated PO reflects the relevant order, supplier, shipping and commercial details. Invoice validation and reconciliation can later connect what was ordered, received and invoiced.
Keeping those concerns connected but distinct avoids two bad extremes.
In the first, the document is just a PDF attachment with no relationship to commerce state. In the second, uploading or validating a document automatically marks money as received.
The system instead treats documents as evidence inside an explicit lifecycle. Operators can inspect the PO while state transitions remain controlled by workflows with named responsibilities.
Adjust the commercial amount after returns
Account-term orders do not stop changing after checkout.
A return can reduce the amount that should remain represented by the purchase-order payment collection. If the commerce order changes while the PO amount remains untouched, finance and operations see two different totals.
The project includes a dedicated adjustment workflow for vendor-side returns. It reads the PO and return context, computes the delta and updates the shared payment collection and split-order authorised amount.
The adjustment carries markers so the same return action is not deliberately applied twice to the PO amount. It also checks that the payment is in an appropriate state before changing the collection.
We make no broader settlement guarantee. The useful business promise is narrower: return adjustments have a named, guarded and retry-aware path instead of relying on somebody to edit a PO total manually.
Why Medusa was the right architectural choice
Medusa supplied payment sessions, providers, collections, orders and workflow primitives. None of those components automatically knows the client's account-term process—and that is the point.
We could extend the commerce engine with a dedicated provider and business states without building a parallel ordering system. The same checkout can offer instant, prepaid and purchase-order modes. The same order model can carry the selected type. The same payment collection can progress through a PO-specific path.
On a less extensible platform, teams often hide account terms behind manual payment, external spreadsheets and status notes. That may launch quickly, but the commercial process becomes invisible to the software.
Here, the client's process became part of the architecture. Medusa remained the foundation; the purchase-order lifecycle expressed what this B2B marketplace actually needed.
What this changed for the client
The buyer could place an account-term order through the normal procurement journey rather than leaving checkout to send emails and spreadsheets.
The marketplace could preserve that payment choice when orders split by seller. Buyers and vendors received distinct actions. Validation no longer masqueraded as money received. Capture had explicit preconditions. Returns could adjust the represented amount through a controlled workflow.
Most importantly, the platform could explain where an order stood.
That clarity matters more than making every PO appear instantly successful. B2B buyers tolerate a multi-stage process when each stage is meaningful. They struggle when the system uses one green badge for several different financial realities.
A practical architecture checklist
Before adding purchase-order payment to a commerce platform, define:
- Is the PO a payment method, a document, or both with separate responsibilities?
- Which payment type is stored on the cart and each resulting order?
- How is that type preserved when a marketplace checkout splits by seller?
- What exactly does PO validation prove?
- Who records buyer payment confirmation?
- What conditions allow the vendor to capture?
- Can validation ever be mistaken for money received?
- Which timestamps and events explain each transition?
- How do returns adjust the payment collection and split-order amount?
- Which retries need stable adjustment markers?
If those answers are explicit, account terms can live inside checkout without losing their financial meaning.
The broader lesson
The client did not need a fake card payment called “purchase order.”
They needed a Medusa checkout that could accept how B2B organisations actually buy: commit now, validate the commercial evidence, confirm the buyer-side payment action and capture only when the supplier-side conditions are satisfied.
We modelled that reality as a dedicated provider and lifecycle. The buyer journey stays coherent. The seller orders preserve the payment contract. Finance sees distinct states instead of an optimistic boolean.
A purchase order can share the commerce engine with instant payments. It should never be forced to tell the same story.